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(57) Abrege/Abstract: 

A method for certified delivery of an outgoing message or messages in a multipoint anonymous, publish/subscribe 
telecommunications system. The system for utilizing the method and program product is one having at least one publisher (10) and 
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at least one subscriber (20). The method is carried out by first establishing a certified delivery session ledger. Next each outgoing 
message is labeled with a label including the delivery session name and a sequence number. The labeled outgoing message or 
messages are then sent to subscribers, and received by a subscriber. Various protocols are described. 
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(54) Title: CERTIFIED MESSAGE DELIVERY AND QUEUING IN MULTIPOINT PUBLISH/SUBSCRIBE COMMUNICATIONS 

(57) Abstract 

A method for certified delivery of an outgoing message or 
messages in a multipoint anonymous, publish/subscribe telecom- 
munications system. The system for utilizing the method and 
program product is one having at least one publisher (10) and 
at least one subscriber (20). The method is carried out by first 
establishing a certified delivery session ledger. Next each outgo- 
ing message is labeled with a label including the delivery session 
: and a sequence number. The labeled outgoing message or 
sges are then sent to subscribers, and received by a sub- 
scriber. Various protocols ate described. 
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What is claimed is: 

1 . In a computer-based publish/subscribe system having a subscriber application that has 
previously subscribed to receive a particular type of message, a computer-implemented 
method for establishing a certified messaging session between a publisher application and the 
subscriber application, the computer-implemented method comprising: 

receiving, at the publisher application, a certified messaging subscription request, said 
certified messaging subscription request including a subscriber name identifying the 
subscriber application and a subject name associated with and identifying the particular type 
of message for which the certified messaging session is to be established; 

responsive to receiving the certified messaging subscription request, establishing the 
certified messaging session with the subscriber application by adding the subscriber name to 
a message ledger at the publisher application, and communicating an acknowledgment 
message to the subscriber application, the acknowledgment message to acknowledge the 
establishment of the certified messaging session; 

attempting to deliver a certified message of the particular type in accordance with the 
certified messaging session by assigning a sequence number to the certified message, 
communicating the certified message from the publisher application to the subscriber 
application, recording a delivery attempt of the certified message in the ledger, and retaining 
the certified message in the ledger at least until the publisher application has received a 
confirmation message from the subscriber application, the confirmation message confirming 
receipt of the certified message at the subscriber application; and 

communicating a confirmation request from the publisher application to the 
subscriber application if the publisher application has not received a confirmation message 
from the subscriber application within a predetermined period of time after attempting to 
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deliver the certified message identified by the assigned sequence number, the confirmation 
request requesting that the subscriber application acknowledge receipt of the certified 
message identified by the assigned sequence number. 

2. The computer-implemented method of claim 1, further comprising: 
responsive to receiving, at the publisher application, a confirmation message 

confirming receipt of the certified message identified by the assigned sequence number at the 
subscriber application, updating the ledger at the publisher application to indicate the 
certified message identified by the assigned sequence number was received by the subscriber 
application. 

3. The computer-implemented method of claim 1, further comprising: 
responsive to receiving, at the publisher application, a confirmation message 

confirming receipt of the certified message identified by the assigned sequence number at the 
subscriber application, deleting the certified message identified by the assigned sequence 
number from the ledger at the publisher application. 

4. The computer-implemented method of claim 1 , further comprising: 
responsive to receiving, at the publisher application, a confirmation message 

confirming receipt of the certified message identified by the assigned sequence number at the 
subscriber application, deleting the certified message identified by the assigned sequence 
number from the ledger if the ledger indicates that all subscriber applications, to which the 
certified message identified by the assigned sequence number has been sent, have confirmed 
receipt of the certified message identified by the assigned sequence number. 

5. The computer-implemented method of claim 1 , wherein the ledger is a file-based 
ledger, and the certified messaging session is persistent beyond termination and restart of the 
publisher application and/or the subscriber application. 
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6. The computer-implemented method of claim 1 , wherein prior to establishing the 
certified messaging session with the subscriber application, the publisher application, with 
which the subscriber application has previously subscribed for a particular type of message, 
publishes messages that are communicated to the subscriber application without the publisher 
application having knowledge of the existence of the subscriber application. 

7. In a computer-based publish/subscribe system having a subscriber application that has 
previously subscribed for a particular type of message, a computer-implemented method for 
establishing a certified messaging session between a publisher application and the subscriber 
application, the computer-implemented method comprising: 

communicating a certified messaging subscription request from the subscriber 
application to the publisher application, said certified messaging subscription request 
including a subscriber name identifying the subscriber application and a subject name 
associated with and identifying the particular type of message for which the certified 
messaging session is to be established; 

receiving, at the subscriber application, an acknowledgement message from the 
publisher application, said acknowledgment message acknowledging the establishment of the 
certified messaging session; 

receiving, at the subscriber application, a certified message from the publisher 
application in accordance with the certified messaging session, the certified message 
identified by a sequence number; 

responsive to receiving, at the subscriber application, the certified message identified 
by the sequence number from the publisher application, updating a ledger at the subscriber 
application to indicate the receipt of the certified message identified by the sequence number, 
and communicating a confirmation message to the publisher application, the confirmation 
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message confirming receipt of the certified message identified by the sequence number at the 
subscriber application; and 

after communicating a confirmation message to the publisher application, receiving a 
confirmation request from the publisher application, the confirmation request requesting a 
confirmation message from the subscriber application to confirm receipt of a certified 
message having a particular sequence number. 

8. The computer-implemented method of claim 7, further comprising: 
verifying whether the ledger indicates a certified message having the particular 

sequence number has been received at the subscriber application, and if so, communicating a 
second confirmation message to the publisher application, the second confirmation message 
confirming receipt of the certified message having the particular sequence number at the 
subscriber application. 

9. The computer-implemented method of claim 7, further comprising: 

after receiving a confirmation request from the publisher application, receiving a 
second certified message having a sequence number indicating a previous certified message 
was sent by the publisher application, but not received by the subscriber application; and 

communicating a certified message request to the publisher application, the certified 
message request including a sequence number associated with a certified message that the 
ledger indicates was not previously received at the subscriber application. 

1 0. The computer-implemented method of claim 7, wherein the ledger is a file-based 
ledger, and the certified messaging session is persistent beyond termination and restart of the 
publisher application and/or the subscriber application. 

11. A publisher application for communicating certified messages to a subscriber 
application via a certified messaging session, the publisher application and the subscriber 
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application part of an anonymous publish/subscribe computer system, the publisher 
application comprising: 

a process to receive a certified messaging subscription request, said certified 
messaging subscription request including a subscriber name identifying the subscriber 
application and a subject name associated with and identifying the particular type of message 
for which the certified messaging session is to be established; 

a process to establish the certified messaging session with the subscriber application 
in response to receiving the certified messaging subscription request by adding the subscriber 
name to a message ledger at the publisher application, and communicating an 
acknowledgment message to the subscriber application, the acknowledgment message to 
acknowledge the establishment of the certified messaging session; and 

a certified delivery process to attempt to deliver a certified message of the particular 
type in accordance with the certified messaging session by assigning a sequence number to 
the certified message, communicating the certified message from the publisher application to 
the subscriber application, recording a delivery attempt of the certified message in the ledger, 
and retaining the certified message in the ledger at least until the publisher application has 
received a confirmation message from the subscriber application, the confirmation message 
confirming receipt of the certified message at the subscriber application, wherein the certified 
delivery process is to communicate a confirmation request to the subscriber application if the 
publisher application has not received a confirmation message from the subscriber 
application within a predetermined period of time after attempting to deliver the certified 
message identified by the assigned sequence number, the confirmation request requesting that 
the subscriber application acknowledge receipt of the certified message identified by the 
assigned sequence number. 
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12. The publisher application of claim 1 1, wherein, responsive to receiving, at the 
publisher application, a confirmation message confirming receipt of the certified message 
identified by the assigned sequence number at the subscriber application, the certified 
delivery process is to delete the certified message identified by the assigned sequence number 
from the ledger at the publisher application. 

13. The publisher application of claim 1 1, wherein, responsive to receiving, at the 
publisher application, a confirmation message confirming receipt of the certified message 
identified by the assigned sequence number at the subscriber application, the certified 
delivery process is to delete the certified message identified by the assigned sequence number 
from the ledger if the ledger indicates that all subscriber applications, to which the certified 
message identified by the assigned sequence number has been sent, have confirmed receipt of 
the certified message identified by the assigned sequence number. 

14. The publisher application of claim 1 1, wherein the ledger is a file-based ledger, and 
the certified messaging session is persistent beyond the publisher application or the 
subscriber application being terminated and restarted. 

1 5 . The publisher application of claim 1 1 , further comprising: 

a messaging process to publish messages with a subject name associated with content 
of the messages, the messages communicated to subscriber applications that have subscribed 
to receive messages having a particular subject name without the publisher application having 
knowledge of the existence of the subscriber application. 

1 6. The publisher application of claim 1 1 , wherein, responsive to receiving, at the 
publisher application, a confirmation message confirming receipt of the certified message 
identified by the assigned sequence number at the subscriber application, updating the ledger 
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at the publisher application to indicate the certified message identified by the assigned 
sequence number was received by the subscriber application. 

17. A subscriber application for receiving certified messages from a publisher application 
via a certified messaging session, the publisher application and the subscriber application part 
of an anonymous publish/ subscribe computer system, the subscriber application comprising: 

a process to communicate a certified messaging subscription request from the 
subscriber application to the publisher application, said certified messaging subscription 
request including a subscriber name identifying the subscriber application and a subject name 
associated with and identifying the particular type of message for which the certified 
messaging session is to be established; 

a process to receive, at the subscriber application, an acknowledgement message from 
the publisher application, said acknowledgment message acknowledging the establishment of 
the certified messaging session; and 

a certified delivery process to receive, at the subscriber application, a certified 

message from the publisher application in accordance with the certified messaging session, 

the certified message identified by a sequence number, and responsive to receiving the 

certified message identified by the sequence number from the publisher application, to update 

a ledger at the subscriber application to indicate the receipt of the certified message identified 

by the sequence number, and to communicate a confirmation message to the publisher 

application, the confirmation message confirming receipt of the certified message identified 

by the sequence number at the subscriber application, wherein, after communicating a 

confirmation message to the publisher application, the certified message process is to receive 

a confirmation request from the publisher application, the confirmation request requesting a 

confirmation message from the subscriber application to confirm receipt of a certified 

message having a particular sequence number. 
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18. The subscriber application of claim 1 7, wherein the certified message process is to 
verify whether the ledger indicates a certified message having the particular sequence number 
has been received at the subscriber application, and if so, to communicate a second 
confirmation message to the publisher application, the second confirmation message 
confirming receipt of the certified message having the particular sequence number at the 
subscriber application. 

19. The subscriber application of claim 17, wherein, after receiving a confirmation 
request from the publisher application, the certified message process is to receive a second 
certified message having a sequence number indicating a previous certified message was sent 
by the publisher application, but not received by the subscriber application, and wherein the 
certified message process is to communicate a certified message request to the publisher 
application, the certified message request including a sequence number associated with a 
certified message that the ledger indicates was not previously received at the subscriber 
application. 

20. The subscriber application of claim 17, wherein the ledger is a file-based ledger, and 
the certified messaging session is persistent beyond the publisher application or the 
subscriber application being terminated and restarted. 
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CERTIEIED MESSAGE DELIVERY AND QUEUING IN MULTIPOINT 
PUBLISH/SUBSCRIBE COMMUNICATIONS 

Background to the Invention 

5 

Technical Field 

This invention relates to multipoint publish/subscribe communications and, more 
particularly, to certified message delivery and queuing between multipoint computer- 
based publisher and subscriber applications. 

10 

Background 

In a typical anonymous public/subscribe technologies ~ such as described in US 
patents 5,557,798; 5,339,392; 5,257,369 and 5,187,787 - a publisher application 
publishes information to requesting or subscriber applications without having any 
15 knowledge of the number, identity or address of any such subscriber applications. In 
fact, no subscriber applications may exist. Instead of knowing about subscribers, a 
publisher will merely publish information applying a context or subject "label" to the. 
published message. A subscriber then identifies desired messages by the content label 
and receives only those messages relevant to the desired content. 

20 

The advantages of such a publish/subscribe, content-based addressing systems are well 
known and include the ability to decouple subscribers and publishers from one another. 
This decoupling allows publishers and subscribers to operate without having any 
knowledge of the identity, location or address, or communication protocols of each 
25 other. The flexibility that this offers is enormous and, accordingly, such 
content/subject-based addressing communication-environments are becoming 
increasingly popular. 

Unfortunately, the very advantages (such as anonymous decoupling) of these systems, 
30 precludes the use of conventional reliable messaging protocols such as TCP. TCP, and 
other reliable messaging protocols apply only in point-to-point type of 
communications. In these point-to-point communications message senders and 
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receivers are directly linked to one another and therefore know each other's addresses 
and locations? 

Unfortunately, these reliable messaging protocols - that guarantee arrival and order of 
5 arrival of messages - require advance knowledge between applications. They are, 
therefore, not applicable to typical publish/subscribe environments. 

Yet, such reliable or certified delivery of messages is extremely important. For 
example, certified delivery is appropriate when a sending application requires 
10 individual confirmation of delivery for each message it sends. For example, a 
travelling sales representative computes sales figures on a lap-top computer, and sends 
them to a supervisor at the office. The user must know for certain that the data has 
arrived, and has been included in the supervisor's sales report. 

1 5 Certified delivery is also appropriate when a receiving application cannot afford to miss 
any messages. For example, in an application that processes orders to buy and sell 
inventory items, each order is important. If any orders are omitted, then inventory 
records are incorrect 

20 In addition, certified delivery is appropriate when each message on a specific subject 
builds upon information in the previous message with that subject. For example, a 
sending program updates a receiving database, contributing part of the data in a record, 
but leaving other parts of the data unchanged. The database is correct only if all 
updates arrive in the order they are sent. 

25 

Furthermore, certified delivery is appropriate in situations of intermittent physical 
connectivity-such as discontinuous network connections, for example, an application 
in which several mobile lap-top computers must communicate with one another. 
Connectivity between mobile units is sporadic, requiring persistent storage of messages 
30 until the appropriate connections are reestablished. 

Thus, a very real need exists for having both the advantages of certified messaging and 
the advantages of content-based, anonymous publish/subscribe environments. 

2 
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SUMMARY OF THE INVENTION 

Briefly, according to this invention a publisher publishes a message to any number of 
unknown subscribers. Note, as used herein "publisher" and "sender" are used 
synonymously, and "subscriber" and "listener" are used synonymously. The message 
5 is published indicating the subject or content using typical content-based 
publish/subscribe protocols. Subscribers interested in receiving information on the 
designated content receive the message without knowing about the publisher. Thus 
the publisher information remains transparent to the subscriber: 

10 In circumstances where the certified messaging is required, the invention provides for 
establishing a message delivery tracking session. This session includes a name and a 
ledger used for tracking. 

Using these functions the system can track delivery of messages and notify 
1 5 publishers/senders if messages are not delivered. In one embodiment of the invention, 
delivery attempts are repeated for a preset time (or number of delivery attempts) to 
ensure or attempt to ensure delivery. 

This invention also extends to queuing messages for certified delivery. This occurs 
20 when certified delivery is required for a one of a group of n possible recipients. The 
system ensures that one (and not all) of the group receives the message. This is 
accomplished by having members of the group indicate their availability or capacity 
and having the system route the message to the subscriber (listener) with the greatest 
availability. 

25 

An extension of this concept is the scheduling of tasks for a group of n possible task 
performers, each available to accomplish a task. Each task doer, notifies the system of 
its availability/ability to accomplish tasks. Tasks are then sent to/queued for each task 
doer according to a rating based on its availability. 
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Accordingly, in one aspect of the present invention there is provided in a computer- 
based publish/subscribe system having a subscriber application that has previously 
subscribed to receive a particular type of message, a computer-implemented method 
for establishing a certified messaging session between a publisher application and the 
subscriber application, the computer-implemented method comprising: 

receiving, at the publisher application, a certified messaging subscription 
request, said certified messaging subscription request including a subscriber name 
identifying the subscriber application and a subject name associated with and 
identifying the particular type of message for which the certified messaging session is 
to be established; 

responsive to receiving the certified messaging subscription request, 
establishing the certified messaging session with the subscriber application by adding 
the subscriber name to a message ledger at the publisher application, and 
communicating an acknowledgment message to the subscriber application, the 
acknowledgment message to acknowledge the establishment of the certified 
messaging session; 

attempting to deliver a certified message of the particular type in accordance 
with the certified messaging session by assigning a sequence number to the certified 
message, communicating the certified message from the publisher application to the 
subscriber application, recording a delivery attempt of the certified message in the 
ledger, and retaining the certified message in the ledger at least until the publisher 
application has received a confirmation message from the subscriber application, the 
confirmation message confirming receipt of the certified message at the subscriber 
application; and 

communicating a confirmation request from the publisher application to the 
subscriber application if the publisher application has not received a confirmation 
message from the subscriber application within a predetermined period of time after 
attempting to deliver the certified message identified by the assigned sequence 
number, the confirmation request requesting that the subscriber application 
acknowledge receipt of the certified message identified by the assigned sequence 
number. 



3a 



CA 02313039 2007-04-30 



According to another aspect of the present invention there is provided in a computer- 
based publish/subscribe system having a subscriber application that has previously 
subscribed for a particular type of message, a computer-implemented method for 
establishing a certified messaging session between a publisher application and the 
5 subscriber application, the computer-implemented method comprising: 

communicating a certified messaging subscription request from the subscriber 
application to the publisher application, said certified messaging subscription request 
including a subscriber name identifying the subscriber application and a subject name 
associated with and identifying the particular type of message for which the certified 
10 messaging session is to be established; 

receiving, at the subscriber application, an acknowledgement message from 
the publisher application, said acknowledgment message acknowledging the 
establishment of the certified messaging session; 

receiving, at the subscriber application, a certified message from the publisher 
1 5 application in accordance with the certified messaging session, the certified message 
identified by a sequence number; 

responsive to receiving, at the subscriber application, the certified message 
identified by the sequence number from the publisher application, updating a ledger at 
the subscriber application to indicate the receipt of the certified message identified by 
20 the sequence number, and communicating a confirmation message to the publisher 
application, the confirmation message confirming receipt of the certified message 
identified by the sequence number at the subscriber application; and 

after communicating a confirmation message to the publisher application, 
receiving a confirmation request from the publisher application, the confirmation 
25 request requesting a confirmation message from the subscriber application to confirm 
receipt of a certified message having a particular sequence number. 

According to yet another aspect of the present invention there is provided a publisher 
application for communicating certified messages to a subscriber application via a 
certified messaging session, the publisher application and the subscriber application 
30 part of an anonymous publish/subscribe computer system, the publisher application 
comprising: 
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a process to receive a certified messaging subscription request, said certified 
messaging subscription request including a subscriber name identifying the subscriber 
application and a subject name associated with and identifying the particular type of 
message for which the certified messaging session is to be established; 
5 a process to establish the certified messaging session with the subscriber 

application in response to receiving the certified messaging subscription request by 
adding the subscriber name to a message ledger at the publisher application, and 
communicating an acknowledgment message to the subscriber application, the 
acknowledgment message to acknowledge the establishment of the certified 
10 messaging session; and 

a certified delivery process to attempt to deliver a certified message of the 
particular type in accordance with the certified messaging session by assigning a 
sequence number to the certified message, communicating the certified message from 
the publisher application to the subscriber application, recording a delivery attempt of 
15 the certified message in the ledger, and retaining the certified message in the ledger at 
least until the publisher application has received a confirmation message from the 
subscriber application, the confirmation message confirming receipt of the certified 
message at the subscriber application, wherein the certified delivery process is to 
communicate a confirmation request to the subscriber application if the publisher 
20 application has not received a confirmation message from the subscriber application 
within a predetermined period of time after attempting to deliver the certified message 
identified by the assigned sequence number, the confirmation request requesting that 
the subscriber application acknowledge receipt of the certified message identified by 
the assigned sequence number. 

25 According to still yet another aspect of the present invention there is provided a 
subscriber application for receiving certified messages from a publisher application 
via a certified messaging session, the publisher application and the subscriber 
application part of an anonymous publish/ subscribe computer system, the subscriber 
application comprising: 

30 a process to communicate a certified messaging subscription request from the 

subscriber application to the publisher application, said certified messaging 
subscription request including a subscriber name identifying the subscriber 
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application and a subject name associated with and identifying the particular type of 
message for which the certified messaging session is to be established; 

a process to receive, at the subscriber application, an acknowledgement 
message from the publisher application, said acknowledgment message 
acknowledging the establishment of the certified messaging session; and 

a certified delivery process to receive, at the subscriber application, a certified 
message from the publisher application in accordance with the certified messaging 
session, the certified message identified by a sequence number, and responsive to 
receiving the certified message identified by the sequence number from the publisher 
application, to update a ledger at the subscriber application to indicate the receipt of 
the certified message identified by the sequence number, and to communicate a 
confirmation message to the publisher application, the confirmation message 
confirming receipt of the certified message identified by the sequence number at the 
subscriber application, wherein, after communicating a confirmation message to the 
publisher application, the certified message process is to receive a confirmation 
request from the publisher application, the confirmation request requesting a 
confirmation message from the subscriber application to confirm receipt of a certified 
message having a particular sequence number. 

Advantages of the Invention 

This invention has a number of advantages. For example, it provides: 
Certainty 

Certified delivery assures application programs that every message reaches 

each 
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intended recipient-in the order sent When delivery is not possible, both 
. ^ sendees and, optionally, listeners receive explicit information about each 

undelivered message. 



Once a program sends a certified message, the system continues delivery 
attempts until delivery succeeds, or until the message's time limit expires. 
Control 

Application programs determine an explicit time limit for each message. 
Sending applications can disallow certified delivery to specific listening 



Detail 

The system can also present advisory messages to inform 
application programs of every significant event relating to delivery. 
Process-Based or File-Based Recording 
The system can also record the status of each message in a 
ledger. Applications that require certification only for the duration of the 
application 

process can choose a process-based ledger. Applications that require 
certification that 

transcends process termination and restart can choose a file-based ledger. 

The invention will be described in greater detail below with reference to the 
accompanying drawings. 

Description of the Drawings 

In the attached drawings: 

Figure 1 is a schematic representation of a typical publish/subscribe environment useful 
for illustrating this invention; and 

Figure 2 is a schematic representation of a typical publish/subscribe environment useful 
in illustrating the distributed queuing and task scheduling aspects of the invention. 

Specific Description 
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Overview 

Figwe 1 snows a publisher application (sender) 10 and a plurality of subscriber 
applications (listeners) 20, 20' and 20". In the preferred embodiment of this invention 
the publisher and subscribers) are software applications based on one or more 
5 computers interconnected by a network 30 providing a data path among the 
applications. The publisher 10 and subscribers) 20 preferably implement a content- 
based communications protocol whereby a publisher publishes a message indicating 
only the content of the message and without knowing the identity or protocols used by 
the subscribers) 20. These inter-application communications are established by 
10 communications daemons 12 (associated with a publisher/sender) and 22, 22' and 22" 
(associated with the subscriber/listener 20, 20' and 20"). The arrangement shown in 
this figure is well known and described in many publications including the patents 
referred to above. 



IS As is described in much greater detail below, a listener 20 can register with a specific - 
publisher 10 to receive certified messages. This communication includes the 
subscribers name, its "inbox" address and the subject/content of messages it requires 
information on. Thus the publisher 10 will have a list of subscriber names and inboxes 
(but know nothing else about the subscriber) for all subscribers wishing to receive 

20 certified messages. The publisher/sender 10 will therefore expect an acknowledgement 
of each message it sends out; an acknowledgement it would receive from a 
subscriber/listener 20, 20' and/or 20". Importantly, if the publisher/sender 10 does not 
receive the acknowledgement, it sends an acknowledgement request message, usually 
for a predetermined time or number of "sends." 

25 

In the event the subscriber wishes to have guaranteed delivery of messages, the 
publisher can save the message to disk (or other storage) until an acknowledgement of 
subscriber receipt occurs. Thus, until message times out, the subscriber can, at a later 
date, receive the message by contacting the publisher. This would usually happen 
30 where messages are very dependent on their sequence or build upon prior message. In 
these circumstances missing/unreceived messages could be catastrophic. Also, in these 
(and in most certified messaging applications of this invention) each certified message 
is assigned a tracking number. This allows both sender and listener/subscriber to 
monitor which messages are received and/or missing. 
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In many applications, data communications are highly reliable, but in some situations 
appliwtiohs^require even stronger assurances of delivery. Certified delivery features 
offers greater certainty of delivery even in situations where processes and their network 
connections are unstable. 

5 

Certified Messaging 

Enabling a Delivery-Tracking Session 

The first step toward certified delivery is to enable a delivery-tracking session. A 
10 delivery-tracking session begins as an ordinary anonymous publish/subscribe session; 
enabling a session adds information so that it can participate in certified delivery 
protocols. The additional information includes a name and a ledger. 

Delivery-tracking sessions can send and receive messages, just as ordinary sessions - 
15 can. In addition, delivery-tracking sessions can participate in certified delivery calls 
(that is, calls in the rvcm library layer); ordinary sessions cannot participate in these 
calls. (Notice the asymmetry. Delivery-tracking sessions can participate in ordinary 
calls, but ordinary sessions cannot participate in certified delivery calls.) 

20 Name 

Each delivery-tracking session has a name which may be reusable, or non-reusable. The 
name identifies the session to other delivery-tracking sessions, and is part of the label 
that identifies outbound messages from the session. 

25 A name is reusable when a program supplies it explicitly to the enabling call. When a 
session with a reusable name also has a file-based ledger, it operates as an instance of a 
persistent correspondent-- which allows continuity of certified delivery beyond session 
termination and program restarts. 

30 Two delivery-tracking sessions must not bind the same reusable name that is, at any 
moment in time, each reusable name must be unique. Sessions may reuse a name 
sequentially, but not simultaneously. Violating this rule can significantly obstruct 
certified delivery. Typically, session names have the same syntax as subject names. 
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Programs may omit a name in the enabling call-in which case the call generates a 
Unique, non-reusable name for the session. No other session on any computer can ever 
have the same name. As a result, a session with a non-reusable name operates as a 
transient correspondent-no subsequent session can continue the certified delivery 
5 behavior of the session. 

Enabling a delivery-tracking session creates a ledger for it. Certified delivery software 
uses the ledger to record information about every unresolved outbound certified 
message, every subject for which this session receives (inbound) certified messages, 
1 0 and other cooperating delivery-tracking sessions. 

Programs may store the ledger in a ledger file, or in process-based storage within the 
running program. (Even when a session uses a ledger file, it may sometimes replicate 
parts of the ledger in process-based storage for efficiency; however, programmers 
1 5 cannot rely on this replication.) 

Ledger files must be unique. That is, two sessions must not use the same ledger file 
(concurrently). If an operating system supports raw disk devices (also called raw 
partitions), a device can be specified as the ledger file. 

20 

A session with a file-based ledger and a reusable name qualifies as a persistent 
correspondent, with certified delivery behavior that can extend beyond session 
termination. 

25 Labeled Messages 

A labeled message is like an ordinary message, except that it includes supplementary 
information, which delivery-tracking sessions can use for certified message delivery: 

30 The name of the delivery-tracking session that sent the message. 

A sequence number assigned by the sending session. 

Sending a Labeled Message 
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Any delivery-tracking session can send a labeled message by using the sending calls in 
Ae certifiedTnessage delivery library layer. Examples of such delivery-Tracking Send 
Calls are in the table below. 



c 


rvcmSend 0, rvcm_SendWithRepiy ( ) 


C++ 


RvCmSenden: certifiedSend ( ), 




RvCmSender:: certifiedSendRequest ( ) 


Java 


RvCmSender. certifiedSend ( ), 
RvCmSender. certifiedSendRequest ( ) 



5 



Receiving a Labeled Message 

For clarity, two kinds of listening endpoints are distinguished. An ordinary listener is a 
listener created with an ordinary listening call, such as the C functions rvListenlnbox ( 
) or rv_ListenSubject 0- A delivery-tracking listener is a listener created with a 
10 delivery-tracking listening call, such as the C functions rvcm_ListenInbox 0 or 
rvcm_ListenSubject 0- 

Either type of listening endpoint can receive a labeled message — delivery-tracking 
listeners (created by the certified delivery library), as well as ordinary listeners. 

15 

When an ordinary listener receives a labeled message, it presents it to the appropriate 
callback function as if it were an ordinary message. That is, it ignores the 
supplementary information that distinguishes a labeled message. 

20 When a delivery-tracking listener receives a labeled message, its behavior depends on 
context: 

If a delivery-tracking listener is registered for certified delivery, it presents the 
supplementary information to the callback function. 

25 If a delivery-tracking listener is not registered for certified delivery, it presents a 

"nulT 

sender's name to the callback function, with a sequence number of zero. 
8 
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- ^ In addition, if appropriate, the certified delivery library automatically requests 
that 

the sender register the listener for certified delivery. 

5 

Discovery and Registration for Certified Delivery 
Discovery 

When a delivery-tracking listener receives a labeled message from a delivery-tracking 
10 sender that is not listed in the listener's ledger, the listener "discovers" the sender on 
the message subject 

Three events follow discovery: 

15 Certified delivery software adds the sender's name to the listener's ledger, as a . 

source of messages on the subject. 

Certified delivery software in the listening program contacts the sending 
program to request registration for certified delivery of the subject and 
20 information regarding the agreement. 

Certified delivery software presents a REGISTRATION. DISCOVERY 
advisory to the listening program. 

25 Registration 

When a delivery-tracking sender receives a registration request from a delivery- 
tracking listener, the sender automatically accepts the request Acceptance consists of 
these four events: 

30 

Certified delivery software registers the listener for certified delivery of the 
subject-recording that fact in the sender's ledger. 

9 
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Certified delivery software in the sending program notifies the listener session 
- ^ that flie registration requested is accepted-the sender accepts responsibility for 
certified delivery on the subject. 

5 Certified delivery software presents a REGISTRATION. REQUEST advisory 

to the sender session, informing it of the new registered listener. 

When the certified delivery software in the listening program receives the 
acceptance reply, it presents a Registration Certified advisory to the listener 
10 session. 

Certified Delivery Agreement 

Following registration and acceptance, the sender and listener have a certified delivery 
1 5 agreement on the subject. 

The sender is responsible to record each outbound message on that subject, and 
to retain the message in its ledger until it receives confirmation of delivery from 
the listener (or until the time limit of the message expires). 

20 

In return, the listener is responsible to confirm delivery of each message, and to 
request retransmission when a message arrives out of sequence. 

The system arranges all of this accounting automatically. The sending and listening 
25 programs do not participate directly in these protocols-only indirectly, by sending and 
listening with certified delivery library calls. 

Notice that a certified delivery agreement applies in one direction only— from a sender 
to a listener. A two-way conversation requires two separate certified delivery 
30 agreements. 

We refer to the two participants in a certified delivery agreement as a certified sender 
and a certified listener, and the labeled messages that flow between them are certified 
messages. Notice the subtle difference in terminology-before establishing a certified 
10 
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delivery agreement, the participants are delivery-tracking senders and listeners; 
afterward, they are certified senders and listeners. A labeled message is only a certified 
message when the sender and receiver maintain a certified delivery agreement. 

5 Delivering a Certified Message 

Once a delivery agreement is in place, all subsequent messages on the subject (from the 
certified sender to the certified listener) are certified messages. Each certified message 
generates a series of protocol events: 



10 When the system presents a certified message to the listening callback function, 

it includes the sequence number assigned (automatically) by the sending 
Software and the publisher's name. 



When the callback function returns, certified delivery software automatically 
confirms delivery to the sender and records confirmation to a ledger. (Programs 
can override this behavior and confirm delivery explicitly.) 

When confirmation reaches the sending program, certified delivery software 
records delivery in the sender's ledger, and presents a Delivery.Confirm 
advisory to the sender session. 



When confirmation has arrived from every certified listener for this message, 
certified delivery software deletes the message from the sender's ledger, and 
presents a DEL [VERY. Complete advisory to the sender session. 

Automatic Confirmation of Delivery 

The default behavior of certified listeners is to automatically confirm message delivery 
upon return from the data callback function. Programs can selectively override this 
behavior for specific listening endpoints (without affecting other listening endpoints). 

By overriding automatic confirmation, the listener assumes responsibility for explicitly 
confirming each inbound certified message. 
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Consider overriding automatic confirmation when processing inbound messages 
involves asynchronous activity, such as computations in other threads, database 
queries, or additional network communications. 

5 Requesting Confirmation 

If a certified sender does not receive prompt confirmation of delivery from a certified 
listener (for example, because of network glitches), the system in the sending program 
automatically requests confirmation. After each request, it presents a DELIVERY. 
NO_RESPONSE advisory to the sending session. 

10 

When a listener receives a request for confirmation, it checks its ledger, and reconfirms 
receipt of the messages that it has already confirmed. (This behavior is identical, 
whether the program uses automatic confirmation, or overrides it.) 

1 S Sequencing and Retransmission 

A delivery-tracking sender assigns sequence numbers serially for each outbound 
subject, so the sequence numbers reflect the order of messages from a sender on a 
specific subject. 

20 When certified delivery software presents certified messages to a certified listener, it 
preserves the sequence in which the sender sent them. If a message arrives out of 
sequence, certified delivery software in the listener does not present it to the callback 
function until all the preceding messages are available. 

25 For example, a certified listener is receiving certified delivery for the subject FOO from 
a sender named BAZ. After receiving and presenting message number 32, the next 
message to arrive is message 35. Certified delivery software holds message 35 until it 
can first present messages 33 and 34. 

30 Meanwhile, the certified delivery software in FOO requests retransmission of messages 
33 and 34 from Baz. In a case where the time limit on those messages has expired-so 
BAZ no longer has them in its ledger— certified delivery software presents a 
Delivery.Unavailable advisory to the listener, indicating that messages 33 and 34 
are no longer available. Then it presents message 35 to the data callback function. 
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Persistent Correspondents 

We introduced the concept of persistent correspondents in the section Name, page 144. 
5 A reusable name and a file-based ledger allow a persistent correspondent to continue 
certified delivery beyond the termination and restart of a session or process. 

Example 

Consider an example application system, in which application program joe generates 
1 0 important information, and sends it to application program SUE in certified messages on 
the subject RememberThis. Upon receipt, SUE stores the information in a database. 

If either joe or SUE terminate unexpectedly, it is crucial that certified messages still 
arrive for entry into the database. To ensure this result, both programs must represent 
15 persistent correspondents-that is, both programs enable sessions with reusable names 
(joe_pc and SUE_PC), and each program keeps a file-based ledger. In addition, SUE 
requires old messages when it enables the session SUEPC. 

During operation, JOE has sent message number 57 on the subject remember.this but 
20 has not yet received delivery confirmation for messages 53- 56. SUE is processing 
message 53, when a sudden hardware failure causes to terminate. Meanwhile, JOE 
continues to send messages 58-77. 

The computer restarts, and SUE restarts. The ledger file for SUE PC indicates that 
25 message 52 was received and confirmed for the subject remember.this for a given 
publisher as joe_pc. On restart sue_pc will contact joe_pc and reestablish their 
certified delivery agreement. When joe accepts, JOE PC retransmits the stored 
messages 53-77 on that subject. 

30 In the above scenario it is important to notice the following: 

That SUE does not miss any remember.this messages. However, the new SUE must 
gracefully fix any difficulties caused by partial processing of message 53 by the old 
SUE. 
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joe and SUE communicate using a broadcast subject name not an inbox. Inbox names 
are unique, so they cannot continue beyond session termination and restart. 

Anticipating a Listener 

In some situations, a delivery-tracking sender can anticipate the request for certified 
delivery from a persistent correspondent that has not yet begun listening. 

Consider an example in which a database program (db) records all messages with the 
subject store.this. The program db enables a session that instantiates a persistent 
correspondent named db_pc. All programs that send messages with the subject 
store.this depend on this storage mechanism. 

One such sending program is Jan. Whenever jan starts, it can anticipate that db_pc 
will request certified delivery of the subject store_this. Suppose that jan starts, but 
db is not running, or a network disconnect has isolated jan from db. Anticipating that 
it will eventually receive a registration request for store.this from db_pc, jan makes 
an add listener call. The effect is that the software within jan behaves as if it has a 
certified delivery agreement with db_pc for the subject store.this. It stores outbound 
messages (on that subject) in its ledger. When db restarts, or the network reconnects, 
jan automatically retransmits all the stored messages to db. 

Cancelling Certified Delivery 

Both listeners and senders can cancel a certified delivery agreement 

Listeners cancel by closing the listening endpoint, using calls listed below. Senders 
with certified delivery agreements to the closed endpoint receive REGISTRation.closed 
advisories. HOST.listen.stop advisories inform other applications of the change. 

Senders can cancel certified delivery of a specific subject to a specific listener. The 
sender program deletes from its ledger all information about delivery of the subject to 
the listener. The sending program receives a registration.closed advisory. If the 
listening correspondent is available (running and reachable), it receives a 
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RECISTRation.not_certified advisory. (Unlike the disallow listener calls in Table 7, 
these calls dfrnot cause denial of subsequent registration requests.) 

Disallowing Certified Delivery 
5 As described before senders automatically accept all registration requests. This is true 
except when the sending program explicitly disallows certified delivery to a listening 
session. Calls that disallow a listener cancel existing certified delivery agreements with 
the listener session (on all subjects), and cause certified delivery software to 
automatically deny subsequent registration requests from the listener session. 

10 

When a sender has disallowed a listener, the events connected with registration do not 
occur. Instead, certified delivery software in the sender notifies the listener session that 
the request is disallowed. When certified delivery software in the listening program 
receives the rejection notice, it presents a REGISTRation.not_certified advisory to the 
IS listening session. 

Allow listener calls supersede the effect of a previous disallow listener call, allowing 
subsequent registration requests from the listener session to succeed. 

20 No Response to Registration Requests 

It is possible that a registration request never reaches the delivery-tracking sender, or 
the acceptance notice never reaches the listening program (for example, because of 
network glitches, or termination of the sending program). After repeated attempts to 
register without response from the sender, certified delivery software in the listening 

25 program presents a registration.no_response advisory to the listening session. After 
several attempts to register with no response, the listener stops sending requests. 

Reusable Names 

Sessions that represent persistent correspondents require reusable names. Reusable 
30 names must obey the syntax for subject names. Reusable names must not contain 
wildcard characters. Reusable names may not begin with reserved elements (such as 
_lNBOX,_RV or _local). For best performance, reusable names should be kept short- 
only a few characters, typically no more than three or four elements, and no more than 
50 characters in total. 

15 
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Ledger Storage Mode 

Each delivery-tracking session records information in a ledger, which occupies storage 
space within the application process. A session that represents a persistent 
correspondent must also keep a copy of the ledger in a file. The file-based ledger 
preserves certified delivery information beyond session (or process) termination and 



This feature has two associated costs: 

The ledger file consumes disk space. 

The application program pauses to update the ledger file at each significant 



Transient correspondents need not pay these costs, because they do not use ledger files. 
However, keeping the ledger in process-based storage consumes process memory. 

Ledger Size 

The size of the ledger depends on several factors-the most important of which is the 
retention rate of stored data. That is, the ledger grows fastest in response to the 
cumulative length of incompletely delivered messages. 

Program developers can estimate the expected size of the ledger, and must ensure that 
the process can allocate sufficient memory to contain it For a file-based ledger, ensure 
that sufficient disk space is available as well, as memory requirements for the process 
application change when utilizing a file-based ledger. 

Event Manager 

The system's certified delivery depends on the event manager for timer and I/O events. 
When an application enables a delivery-tracking session, that session must be an event- 
managed session. 

No Synchronous Sessions 
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Synchronous sessions are not valid for certified delivery calls and all delivery-tracking 
sessions miisTbe asynchronous, event-managed sessions. 

Distributed Queues 

The system also provides use of distributed queues for one-of-n certified delivery. In 
particular, the system provides for distributed queueing of messages along with 
certified/guaranteed delivery in a "one-of-n" delivery mechanism. 
This delivery mechanism is illustrated in Figure 2 in which a single publisher 202 is 
publishing messages to three registered subscribers 204, 206 and 208 respectively. One 
of the subscribers, 206 is a large group of n-subscribers. 

Distributed queueing addresses the problem that it is undesirable for all n-subscribers in 
registered subscriber 206 to get every message published by publisher 202. For 
example, it may be undesirable because each of the n-subscribers in group 206 will take 
an action. In addition, if each subscriber is to receive the message (and possibly 
respond to it) this will consume additional network bandwidth. 

Nonetheless, it is imperative (hence the need for certified/guaranteed delivery) for at 
least one of the n-subscribers in group 206 to receive the message. I.e., ideally the 
system should deliver the message to only one of the n-subscribers 206. This type of 
situation arises where a large number n of subscribers 206 is required to provide the 
desired level of fault tolerance and/or load balancing. Fault tolerance is important in 
situations where applications may be unstable or message delivery is absolutely critical. 

In the system of the invention, each subscriber application in the group 206 operates by 
sending messages to another of the n-subscribers in the group 206 acting as a scheduler 
giving an indication of its weight. The scheduler then responds by sending the message 
to the particular subscriber in the group with the greatest weight Greater details of 
how this is accomplished follow directly below. 

Accordingly, a distributed queue of subscribing database servers 206 can accept 
certified messages that represent tasks (updates and queries). The system assigns each 
task to exactly one of the servers, while the group of servers and the distribution of 
tasks remains completely transparent to the client processes. 
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Queue Members 

The member sessions of a distributed queue all share the same reusable correspondent 
name indicating that they are members of the queue with that name. Each member of a 
distributed queue listens for the same subjects~yet even when n members listen, for 
each inbound message (or task), only one member processes the message. 

Member Roles— Worker and Scheduler 

As used herein with respect to queueing and queued delivery, the terms "listener" and 
"worker" are used interchangeably. Each distributed queue member session can have 
two distinct roles— as a worker, and as a potential scheduler. 

In the listener or worker role, queue member sessions support a limited subset of 
certified delivery calls; members can listen to a subject, override automatic 
confirmation of delivery and confirm delivery. Queue member sessions do not support 
any other certified delivery calls (in particular, calls associated with sending certified 
messages). However, they do support all standard calls (for example, sending ordinary 
messages). 

The system includes fault tolerance software that maintains exactly one active 
scheduler in each queue; if the scheduler process terminates, another member assumes 
the role of scheduler. The queue member session in the scheduler role assigns inbound 
tasks to listeners in the queue. (A scheduler can assign tasks to its own listener 
component, but only does so when all other listeners are busy.) 

The Scheduler as a Feat-Tolerant Component 

Although any queue member has the potential to become the scheduler, fault tolerance 
software maintains exactly one scheduler at all times. Fault tolerance parameters guide 
the software to select the most suited member as scheduler. 

Scheduler weight represents the ability of a member session to fulfill the role of 
scheduler, relative to other members of the same queue, i.e., the greatest availability or 
unused member resources. The queue members use relative scheduler weight values to 
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elect one member as the scheduler, members with higher scheduler weight take 
precedence. ~ 

The active scheduler sends heartbeat messages at the interval specified by the user. 
5 Heartbeat messages inform other members that a member is acting as the scheduler. All 
sessions in the queue must specify the same scheduler heartbeat interval. 

In addition, all sessions in the queue must specify the same scheduler activation 
interval. When the heartbeat signal from the scheduler has been silent for this interval 
10 the queue member with the greatest scheduler weight takes its place as the new 
scheduler. 

Assigning Tasks to Workers 

The scheduler assigns each task to a worker or listener (another queue member - 
15 session). That worker or listener alone processes the task message in a data callback 
function. 

Worker Weight 

Relative worker or listener weights assist the scheduler in assigning tasks. When the 
20 scheduler receives a task, it assigns the task to the available worker or listener with the 
greatest worker or listener weight. 

Enabling a session as a queue member tacitly sets its worker or listener weight 
parameter to 1 . That is, all members implicitly have the same worker or listener weight, 
25 unless program code explicitly changes the worker or listener weight. ' 

Availability 

When the scheduler receives a task, it assigns the task to the available worker listener 
with the greatest listener weight. 

30 

A worker listener is considered available unless either of these conditions are true: 
The pending tasks assigned to the worker or listener exceed its task capacity. 
The worker or listener session is the scheduler. (The scheduler assigns tasks to 
its own "Worker or listener only when all other workers or listeners are busy.) 
19 
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Tas k Capacity 

Task capacity is the maximum number of tasks that a worker or listener can accept. 
When the number of accepted tasks reaches this maximum, the worker or listener 
5 cannot accept additional tasks until it completes one or more of them. 

When the scheduler receives a task, it assigns the task to the worker or listener with the 
greatest worker or listener weight-unless the pending tasks assigned to that worker or 
listener exceed its task capacity. When the preferred worker or listener has too many 
1 0 tasks, the scheduler assigns the new inbound task to the worker or listener with the next 
greatest worker or listener weight. 

Enabling a session as a queue member tacitly sets its worker or listener task capacity to 
1 . Programmers can tune task capacity based on two factors: 

15 

Multi-tasking program on multiprocessing hardware. 

On a multiprocessing computer, a multi-threaded program that devotes n 
threads and n processors to inbound tasks has task capacity n. 

20 

Communication time lag. 

In most distributed queue applications, the communication time is an 
insignificant fraction of the task turnaround time. That is, the time required to 
25 assign a task and signal its completion is very small compared to the time 

required to process the task itself. For example, when average task turnaround 
time is 2000 milliseconds, of which communication time contributes only 10 
milliseconds to the total, then task capacity is the same as the number of 
processors or threads. 

30 

However, in some situations communication time can be significant-for example, 
when the queue members are distributed at distant sites connected by a WAN. When 
communication time is significant, the meaning of task capacity changes; instead of 
signifying the number of tasks that a listener can process concurrently, it signifies the 

20 
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number of tasks that can fill the listener's capacity despite the communication time 
lag. For example, when the average task turnaround time is 1500 milliseconds, of 
which the average task processing time contributes 1000 milliseconds to the total, 
then setting the task capacity to 3 minimizes the listener's idle time between tasks. 
5 When tuning task capacity to compensate for communication time lag, balance is 
critical. Underloading a listener (by setting its tasks capacity too low) can cause the 
listener to remain idle while it waits for the schedule to assign its next task. 
Conversely, overloading a listener (by setting its task capacity too high) can cause 
some assigned tasks to wait, while other listeners that might have accepted those tasks 
10 remain idle. 

TASK SCHEDULING 

In a further application of this invention, the broad concepts of distributed queuing 
can be applied to scheduling tasks for different task doing applications. In this 
15 application an application can be either a scheduler or a worker or both. Each worker 
is assigned a weight indicating its ability to do work, usually the number of tasks it 
can do simultaneously. Typically, workers assign their own weights. 

One application/member of a group becomes the scheduler. Once this occurs, all other 
20 applications become designated workers only. The scheduler becomes both a worker 
and the scheduler. 

When a task is received by the group (the scheduler) it assigns the task to the worker 
with the highest "weight" or ability to do tasks. The worker then calls back to the 
25 scheduler accepting the task and, upon completion, returns a call to the scheduler 
indicating this fact. In certain instances, the call back to the scheduler includes both an 
acceptance and a notification of task completion. 

Two Appendices, A and B are attached. These appendices include detailed C coding 
30 information respectively for Certified messaging and for message queuing. 



21 
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The invention now being fully described, it will be apparent to one of ordinary skill in 
the art that many changes and modifications can be made thereto without departing 
from its spirit or scope. 



22 
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Appendix A: Certified Message Delivery (Programming Details for C 
Programmers) 

As indicated previously, even though some communications are highly reliable, certain 
5 applications require even stronger assurances of delivery. Certified delivery features 
offers greater certainty of delivery even in situations where processes and their network 
connections are unstable. 

This Appendix A provides programming details for C programmers wishing to 
10 implement Certified message Delivery. The Appendix provides, in Table Al, an 
overview listing of Certified's messaging Deliver Datatypes and Functions. Each 
Datatype or Function is then described in greater detail with Cross-references to related 
Datatypes or Functions. 

15 

Certified Message Delivery CAPI 

The following table summarizes the datatypes and functions in the certified message 
delivery C API. 

20 
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Table Al : Certified Message Delivery: Datatypes and Functions 



ItM 


Description 


rvcmJSnable ( ) 


Enable an existing session for delivery tracking. 


rvcm_ListenSubject ( ) 


Listen for broadcast messages, and request certified delivery 
whenever available. 


ivcTn_ListenInbox ( ) 


Open a delivery-tracking inbox to listen for point-to-point 
messages, and request certified delivery whenever available. 


rvcm_Callback 


Function type of callback functions that receive and process 
inbound messages for delivery-tracking listeners. 


rvcm_ListenId 


Certified listening calls return identifiers of this type. 


rvcmseq 


Certified messages bear sequence numbers of this type. 


rvcm_close ( ) 


Close a delivery-tracking endpoint; stop listening for 
messages on it 


rvcm_Scnd ( ) 


Send a labeled message, and track delivery to cooperating 
listeners. 


rvcmSendWithReply ( ) 


bend a labeled request message, and track delivery to 
cooperating listeners. 


rvcmAddListener ( ) 


Pre-register an anticipated listener. 
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Item 


Description 




Cancel certified delivery of a «~ i _ • 
wuvcry m a suoject to a listening 

correspondent 


rvcmDisallowListenerO 


Cancel certified delivers nf B u c<.u:_- . ,. 

ucnvcry or all subjects to a listening 

correspondent, and deny subsequent registration requests. 


rvcm_AllowListenerO 


Invite a receiver to reinstate certified 
delivery for its listeners. 


rvcm_NoAutoConfinnO 


Override automatic confirmation of 
delivery. 


rvcm_confirm() 


Confirm delivery of a certified 
message. 


rvcm_ReviewLedger() 


Summarize the delivery status of 
messages in the ledger, 


rvcm_ReviewCallback 


Function type of callback functions that 
process ledger information for 
rvcm_RevicwLedgcr(). 


rvcm_SyncLedgerFileO 


Synchronize the ledger file. 


rvcm_Error 


Datatype. Enumerates error codes for 
the certified message delivery API. 


rvcm_ErrorTextO 


Return a text string describing an error 
code. 
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Declaration 

5 rvcm_Error rvcm_Enable ( 



rv_N'ame name, 

rvName reserved, 

char* ledgerFile, 

10 rvBoolean requireOldMsgs 

Purpose 

Enable an existing session for delivery tracking. 

15 

Remarks 

All other rvcm functions require an enabled session as an argument Programs must 
call rvcmEnable ( ) before any other calls related to certified delivery. 

20 

A user can use an enabled session for both certified and non-certified 
communications. For example, an enabled session supports calls to rvcm_Send ( ) and 
rv_Send (). 

25 Once a session is enabled for certified delivery, it remains enabled until terminated 
with rv_Term O-The user cannot subsequently change the certified delivery 
parameters of the session. 



30 rvcm_Enable ( ) promotes its session argument to a delivery-tracking session. 

If name is NULL, then rvcm_Enable ( ) generates a unique, non-reusable name for 
this s< 
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If name is non-NULL, then the session binds that name. A correspondent can persist 
beyond session termination only when it has both a reusable name and a file-based 
ledger. 

5 Ledger File 

Every delivery-tracking session stores the state of its certified communications in a 
ledger, which is stored in memory associated with the process. 

10 If ledgerFile is NULL, then this session uses a only process-based ledger. When the 
session or process terminates, all information in the ledger is lost. 

If ledgerFile specifies a valid file name, then this session uses that file for ledger 
storage. If the session or process terminates with incomplete certified 
1 5 communications, the ledger file records that state. When a new session binds the same 
reusable name, it reads the ledger file and continues certified communications from 
the state stored in the file. 

Even though a session uses a ledger file, it may sometimes replicate parts of the 
20 ledger in process-based storage for efficiency; however, programmers cannot rely on 
this replication. 

If the operating system supports raw storage devices (also called raw partitions), the 
user can specify such a device as the ledger file. 

25 

An optional prefix determines whether writing to the ledger file is a synchronous 
operation: 

■ To specify synchronous writing (the default), either supply an ordinary file 
30 name, or prepaid the string sync* to the file name; for example, "myLedger" 

(implicit) or "sync*/local/myLedger" (explicit). Each time a ledger item is 
written, the call does not return until the data is safely stored in the file system. 
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■ To specify asynchronous writing, prepend the string nosync* to the file name; 
for example, "nosync*/local/myLedger". The ledger file might not accurately 
reflect program state in cases of hardware or operating system kernel failure. 

5 A program that uses an asynchronous ledger file can explicitly synchronize it 

by 

calling rvcm_SyncLedgerFileO, described below. 



Parameters 

10 



Parameter 


Description 


session 


Enable this session for certified delivery tracking. 


name 


Bind this reusable name to the session, so the session represents a 
persistent correspondent with this name. 




If non-Null, the name must conform to the syntax rules for subject 
names. It cannot begin with reserved tokens. It cannot be a non-reusable 
name generated by another call to rvcm_Enable(). 




If this argument is NULL, then rvcm_Enab!e() generates a unique, non- 
reusable name for the duration of the session. 


reserved 


This parameter is reserved for future enhancement. The user must 
supply NULL for foilNard compatibility. 
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Parameter 


Description 


ledgerFtte 


If this argument is non-NULL, then this session uses a file-based ledger. 
The argument must represent a valid file name. Actual locations 
corresponding to relative file names conform to operating system 
conventions. 

Prepending nosync* to the file name specifies asynchronous output to 
the file system, sync* or no prefix specifies synchronous output 
(flushed before each output call returns). 

If this argument is NULL, then this session uses a process-based ledger. 


requireOldMsgs 


This parameter indicates whether a persistent correspondent requires 
delivery of messages sent to a previous session with the same name, for. 
which delivery was not confirmed. Its value affects the behavior of 
other delivery-tracking senders. 

If this parameter is RV_TRUE and name is non-NULL, then this 
session requires certified senders to retain unacknowledged messages 
sent to this persistent correspondent. When this session begins listening 
to the appropriate subjects, the senders can complete delivery. (It is an 
error to supply RV_TRUE when name is NULL.) 

If this parameter is RV FkLSr., then this session does not require 
certified senders to retain unacknowledged messages. Certified senders 
may delete those messages from their ledgers. 
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RVCM Error Code 


Indicates 


RVCM.OK 


No error. The call completed successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session argument that 
is not a valid rv_session (for example, NULL, 
or a session that has already terminated). 


RVCM ERR BAD SESSION NAME 


name. 


RVCM_ERR_NO_MEMORY 


The function could not complete because the 
operating system denied its request to allocate 
storage. 


RVCM ERR FILE IO ERROR 


rvcm .Enable ( ) encountered an error while 
opening the ledger file. For example, an 
explicitly named directory does not exist 


RVCM FRR FIT P NO PFR MISSION 


File privileges are insufficient for 
rvcra_Enable ( ) to open, the ledger file. 


RVCM_ERR_LEDGER_NAME_CONFLIC 
T 


rvcm_Enable ( ) received NULL as the name 
parameter, out a nOn-NULL value as the 
ledgerFile parameter. 


RVCM_ERR_PARAMETER_CONFLICT 


The function received conflicting values for 
parameters. 

ivcmJEnable ( ) received RV_FALSE as its 
requireOldMsgs parameter, and NULL as its 
name parameter. A non-reusable name implies 
a transient correspondent, which cannot have 
backlog messages. 
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RVCM Error Code 


Indicates 1 


RVCM_ERR_FILE_NOT_LEDGER_OWN 
ER 


The reusable name recorded in the file differs 
from the name of this session. rvcm_Enable ( ) 
stopped reading the file. 


RVCM_ERR_CORRUPT_LEDGER_FILE 


The ledger file is corrupt. 
rvcm_Enable ( ) could read only part of the 
ledger file into process-based memory. Some 
information may be lost. 


RVCM_ERR_SESSION_ALREADY_ENA 
BLED 


rvcm_Enable ( ) received a session that is 
already enabled for delivery tracking. It is 
illegal to enable a session more than once. 



Coding Example 

5 cm_err = rvcm_Enable(sess, "CM_EXAMPLE'\ NULL, 
"my_ledger_file", RVTRUE); 

if(cm_err!= RVCM_OK) 
{ 

10 fprintf(stderr, 'Can't enable CM session~%s\n\ 

rvcmErrorText (sess, cmerr) ); 
exit(-l); 
} 

IS See Abo 

rvcm_SyncLedgerFileO, below 



20 rvcmJListenSubjectO 

Function . 
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Declaration 



rvcm_Error rvcm_ListenSubject ( 
rv_Session sessi 



session, 



5 



rvcm_LisCen!d* 



listenid, 
subject, 

dataCallbackFn, 
closureArg ) 



rv_Name 



rvcm_Callback 



rvOpaque 



10 Purpose 



Begin listening for messages that match the subject, and request certified delivery 
whenever available. Whenever a message arrives, the callback function receives it. 



This function is parallel to rv_ListenSubject ( )~it creates an endpoint to receive 
messages with matching subjects. The endpoint receives both labeled messages and 
ordinary messages. 



When a labeled message arrives from an unfamiliar delivery-tracking session, the 
receiving session requests certified delivery for the subject. If the sending session 
accepts the request, then the two sessions cooperate to certify delivery of subsequent 
messages with this subject. 



Unlike ordinary listening endpoints, the user cannot maintain more than one delivery- 
tracking listening endpoint per subject. When one endpoint is already open, 
subsequent calls to rvcm_ListenSubject() with the same subject return an error. (This 
restriction applies to each delivery-tracking session; however, a program with several 
30 delivery-tracking sessions can open independent delivery-tracking listeners with 
identical subjects.) 

Unlike rv_ListenSubject(),the user cannot use rvcm_ListenSubject() to listen to 
wildcard subjects. 



15 



Remarks 



20 



25 
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The software automatically confirms message delivery when the data callback 
function returns. 



5 

Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


listenld 


When rvcm_ListenSubject() returns (without error), this location 
contains a handle denoting the new endpoint To stop listening on the 
subject, pass this handle to rvcm_Close(). 




Wildcard subjects are illegal. 


dataCallbackFn 


When a message arrives, pass it to this callback function. 


closureArg 


Pass this closure argument to the callback function. This argument must 
be a pointer, but it can point to any type of data. It contains any 
information needed by the callback function. This argument is treated 
as an opaque closure, forwarding it to the callback function without 
accessing its value. 
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RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session argument 
that is not a valid rv_session (for example, 
NULL, or a session that has already 
terminated). 


RVCM ERR BAD ARG 


The function received an illegal argument. 
rvcm_ListenSubject() received either a 
NULL callback function, or a NULL listenid 
pointer. 


RVCM_ERR_NO_MEMORY 


The function could not complete because the 
operating system denied its request to 
allocate storage. 


RVCM_ERR_BAD_SUBJECT 


rvcm_ListenSubject() received an ill-formed 
subject name. 

Either it is NULL, or contained too many 
total characters, too many characters in an 
element, too many elements, a wildcard 
character, or an illegal prefix. 


RVCM_ERR_DUPLICATE_SUBJE 
CT 


rvcm_ListenSubject() Can maintain at most 
one open listening endpoint per subject (per 
session): it cannot open a second listening 
endpoint for this subject. 


RVCM_ERR_SESSION_NOT_ENA 
BLED 


The function received a session that is not 
enabled for delivery tracking. 


SUBS7TTUTE S 
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Coding Example 

cm_err =5-rvcm_ListenSubject(sess, &listenld, subject, 
CM_callback, my Closure); 
if (cm_err != RVCM_OK) 
5 fprintf(stderr, "error %s listening to \"%s\"\n", 

rvcm_ErrorText (sess, cm_err). subject); 



See Abo 

10 rvcm_Callback; 
rvcmJListenld; 
rvcm_ListenInbox(); 
rvcm_Close(), all described below 



15 



rvcm_Listenlnbox() 



rvcm_Error rvcmListenlnbox ( 

rvSession session, 

rvcm_ListenId* listenid, 

rv_Name in box, 

rvSize inboxLimit, 

rvcm_Callback dataCallbackFn, 

rv_Opaque closureArg) 



30 Open an inbox and begin listening for point-to-point messages addressed to it. 
Request certified delivery whenever available. Whenever a message arrives, pass it to 
the callback function. 
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This function js parallel to rvJListenlnbox ( )-ix creates an inbox to receive point-to- 
point messages. The inbox receives both labeled messages and ordinary messages. 

When a labeled message arrives from an unfamiliar delivery-tracking session, the 
5 receiving session requests certified delivery for the inbox name. If the sending session 
accepts the request, then the two sessions cooperate to certify delivery of subsequent 
messages to this inbox. 

Certified delivery to an inbox is limited to the duration of the inbox. Once the users 
1 0 closes an inbox or terminates its session, the inbox and its name become obsolete; the 
user can never open another inbox with the same name. Since the system can never 
complete delivery of messages addressed to an obsolete inbox, it automatically deletes 
stored messages when it detects that an inbox has become obsolete. 

1 5 The system automatically confirms message delivery when the data callback function 



Panuaeters 



Parameter 


Description 


session 


A delivery-tracking session. 


listenld 


When rvcm_ListenInbox ( ) returns (without error), this 
location contains a handle denoting the new inbox. To 
stop listening, pass this handle to rvcm Close ()• 


inbox 


Location to store the generated name of the new inbox. 
The allocated space must be at least 
RV_t,mX_INBOX_NAME (currently 100 bytes). 


inboxLimit 


Number of bytes allocated to store the new inbox name. 


dataCallbackFn 


When a message arrives, pass it to this callback function. 
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Parameter - 


Description 


'closureArg 


Pass this closure argument to the callback function. This 

argument must be a pointer, but it can point to any 
type of data. It contains any information needed by the 
callback function, the system treats this argument as an 
opaque closure, forwarding it to the callback function 
without accessing its value. 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_session (for example, NULL, or a 
session that has already terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. rvcm_Listenlnbox ( ) 
received either a NULL inbox name 
pointer, a NULL callback function, 
or a NULL listenid pointer. 


RVCM_ERR_NO_MEMORY 


The function could not complete 
because the operating system denied 
its request to allocate storage. 


RVCM_ERR_SESSION_NOT_ENAB 
LED 


The function received a session that 
is not enabled for delivery tracking. 



5 

Coding Example 
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char inboxName [RV_MAX_INBOX_NAME] ; 



cm_eir = rvcm_ListenInbox(sess, Alistenld, inboxName, sizeof(inboxName), 
CM_caIlback, myClosurc); 
5 if (cm_crr !« RVCMJDK) 

fprintfi(stderr, "error %s listening to certified inbox.\n", 
rvcm_ErrorText(sess, cm_err)); 

See Abo, 

1 0 rvcm.Callback, below 
rvcm_ListenId, below 
rvcm_ListenSubjectO, above 
rvcm_Close(). below. 



15 



rvcm_Callback 

Datatype 



25 



30 



void* rvcm_Callback ( 




rv Session 


session, 


rv Name 


subject, 


rv_Name 


replyName 


rvms R_Type 


msgType, 


rvmsg_Size 


msgSize, 


rvnugData 


msg, 


rvcm_Seq 


sequenceNum, 


rvName 


senderName, 


rvOpaque 


closureArg ) 



Purpose 
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rvcm_Callback is the function type of data callback functions to delivery-tracking 
listeners^Applications define functions of this type to receive inbound messages and 
take appropriate actions. 

S Remarks 

This function type is parallel to rv_Callback. Notice that its function signature 
includes two additional parameters, senderName and sequenceNum, to receive the 
tracking data that labels the inbound message. Application programs can use these 
arguments for testing and auditing. 

10 

The system automatically confirms message delivery when the data callback function 
returns. 

The user can write several callback functions to process the various kinds of messages 
1 5 that the application expects to receive. The user can use the same callback function to 
process messages at several endpoints. Callback functions can take any action in 
processing a message, except for the following restrictions: 

■ Callback functions must not attempt to modify the data (the values of the 
20 parameters msg, subject, reillyName and senderName) in any manner. The 

callback function receives data through pointers; the actual data resides in 
memory that does not belong to the application. The data pointers remain valid 
only until the callback function returns. 

25 ■ The data callback functions must return promptly. 
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Parameters 



Parameter 


Description 


session 


This parameter receives the current session. 


subject 


This parameter receives the destination subject name of 
the inbound message. 

Do not modify this value. This pointer remains valid 
only until the callback function returns. 


replyName 


If the inbound message carries a name for replies, this 
parameter receives it. Otherwise NULL. 

Do not modify this value. This pointer remains valid 
only until the callback function returns 


msgType 


This parameter receives the datatype of the message. 


msgSize 


This parameter receives the size (in bytes) of the 
message. 


msg 


This parameter receives a pointer to the message data. 

Do not modify this value. This pointer 
remains valid only until the callback function returns. 


scquenceNum 


If the message is certified, this parameter receives the 
sequence number that the sender assigned to the 
message. Otherwise, this parameter receives zero. 


senderName 


If the message is labeled, this parameter receives the 
name of the delivery-tracking session that sent the 
message. Otherwise, this parameter receives NULL. 

Do not modify this value. This pointer remains valid 1 
only until the callback function returns. 
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closure Arg 



This parameter receives a closure argument supplied by 
the application when it began listening. This argument is 
a pointer, but it can point to any type of data. It contains 
any information needed by the callback function, the 
system treats this argument as an opaque closure, 
forwarding it to the callback function without 
accessing its value. 



Coding Example 

5 This example code illustrates a data callback function for receiving 
certified delivery. 

void 

CM-callback( 

10 rvSession session, 

rv_Name subject, 

rv_Name replyName, 

rvmsg_Type msgType, 

rvmsg_Size msgSize, 
1 5 rvmsg_Data msg, 

rvcm_Seq seqNumber, 

rv_Name sender, 

rv_Opaque myClosureArg ) 

{ 

20 

printf( ,4 Received: subject=%s, reply=%s, message=", 

subject, (replyName!=NULL ? replyName : "<none>")); 
rvmsg_PrintItem(session, msgType. msgSize, msg, NULL); 
printiHn"); 

25 printf(" sequence number=%ld, sende^/os^", 

seqNumber, (sender!=NULL ? sender : "<none>")); 
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fflush(stderr); 

-L " 

See Also 

5 

rvcm_ListenId; rvcm_Seq; and rvcm_Close(), below. 
rvcm_Listenld 

10 

Datatype 
Declaration 

typedef void* rvcm_ListenId; 

15 

Purpose 

The rvcm_ListenSubject ( ) arid rvcm Listenlnbox ( ) functions return a handle of 
type rvcm_ListenId. To stop listening for the corresponding information, pass this 
handle to rvcmClose ( ). 

20 

Remarks 

an rvcm_ListenId is not meaningful outside of the session in which it was created. 
Each rvcm_ListenId is a unique handle representing an association between a subject 
and a callback function. Use rvcmJListenld only within the local program that 
25 receives it from one of the listening functions, and treat it as opaque. 

rvcmSeq 

Datatype 

30 

Declaration 

typedef unsigned long rvcm_Seq; 
Purpose - 
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Sequencejiumber of a labeled message. 
Remarks 

5 Sequence numbers are limited to 32 bits on all platforms (even platforms that support 
64-bit integers). 

rvcm_CloseO 

10 Function 

Declaration 

rvcmError rvcm_Close ( 

rv_Session session, 
15 rvcm_ListenIdlistenid 

Purpose 

Close a delivery-tracking endpoint; stop listening for messages on it. 

20 Remarks 

This function is parallel to rvClose ()• 

Cooperating senders receive a REGISTRATION. CLOSED advisory, indicating that 
the delivery tracking agreement is no longer in effect. Senders receive a DELIVERY. 
25 FAILED advisory for each undelivered message to the closed endpoint. and the 
system removes undelivered messages from the sender's ledger. 

The system deletes the listener's ledger items corresponding to the closed subject. 

30 When rvcm_Close ( ) closes an endpoint, it generates a HOST.LISTEN.STOP 
advisory message to inform other applications that this application has stopped 
listening to the subject. 
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It is important that a persistent listener close a delivery-tracking endpoint when it no 
longer requires certified delivery of the corresponding subject-and only then. Open 
endpoints cause certified senders to store messages in the ledger while awaiting 
delivery confirmation from the sender. From the sender's perspective, a persistent 

5 listener that exits without closing its listening endpoints appears the same as a listener 
that terminates abnormally; the sender continues to store messages awaiting the return 
of the Listener process. Once an endpoint is closed, senders do not store certified 
messages for that listener, and successive listener processes with the same 
correspondent name do not receive certified delivery of messages sent in the interim. 

10 

Coding Example 

Close endpoints when the application is finished receiving data. Closing endpoints 
lets TiB/Rendezvous software re-use the associated storage resources. After closing. 
15 an endpoint, delete all references to it, to guard against closing it twice. 

It is illegal to close the same endpoint more than once. On some platforms, the error 
R VC M ERR NONEXI STENT I D results; on other platforms, the result can be a 
fatal error 

20 (because it references dynamically allocated memory that has been freed). 

This code fragment illustrates the recommended idiom for closing endpoints: 

if(foo->listenId != NULL) 
25 (rvdm_Close(foo->listenId); 

foo->listenld - NULL; } 
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Parameter 


Description 


session 


The delivery-tracking session that created the endpoint. 


listenld 


Close the endpoint that this handle denotes. 



Errors 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed successfully. 


RVCM_ERR_INVALID_SESS1 
ON 


The function received a session argument 
that is not a valid rv Session (for example, 
NULL, or a session that has already 
terminated). 


RVCM ERR BAD ARG 


The function received an illegal argument, 
rvcm CloseO received a NULL listenld 


RVCM_ERR_NONEXISTENT_ 
ID 


rvcm_Close () received a NULL listenld 
pointer either it is NULL, or it points to 
something other than an rvcm_Listenld, or it 
points to an endpoint that has already been 
closed. 


RVCM_ERR_NO_MEMORY 


The function could not complete because the 
operating system denied its request to 
allocate storage. 


RVCM_ERR_SESSION_NOT_E 
NABLED 


The function received a session that is not 
enabled for delivery tracking. 
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See Also 

.rvcmjListenld, above. 
rvcm_SendO 

5 Function 

Declaration 

rvcmError rvcm_Send ( 

rv_Session session, 

10 rv_Name subject, 

rvmsg_Type rasgType, 

rvmsg_Size msgSize, 

rvmsg_Data rasg, 

unsigned long timeLimit, 

15 rvcm_Seq* sequenceNum ) 

Purpose 

Send a labeled message, and track delivery to cooperating listeners. 
20 Remarks 

This function is parallel to rv_Send (). Notice that its signature includes two 
additional parameters, timeLimit and SequenceNum. 

Use timeLimit to specify the duration of the message (in seconds). The system retains 
25 the message in its ledger until either it receives delivery confirmation from all 
cooperating listeners, or the timeLimit expires. If the time limit expires before 
delivery is complete, the system removes the message from the ledger, and generates 
a DELIVERY. FAILED advisory message listing the cooperating listeners that did 
not confirm delivery of the message. 

30 

We recommend a timeLimit value greater than 60 seconds, since the domain holds 
messages for 60 seconds. 
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rvcm_Send ( ) labels the message with the name of the delivery-tracking session and a 
sequence-number. rvcm.Send ( ) passes the sequence number back to the caller in its 
sequenceNum parameter (the user can use this number for auditing). 

5 Each sending session maintains a separate sequence for each subject it sends. As a 
result, receivers can uniquely identify each labeled message by the three data callback 
arguments subject, senderName and sequenceNum. 

When msg has self-evident length, the user may supply zero for msgSize (the system 
10 computes the actual size automatically). Types with self-evident size are 
RVMSG_RVMSG, RVMSG_STRING (when the string is NULL-terminated) and 
RVMSG_ENCR YPTED . All other types require an explicit size argument in this 
call. 



15 rvcmJSendf) 



rvcm_Send () copies its arguments. After rvcm_Send ( ) returns, the user may free or 
reuse the storage (for example, a message buffer). 

20 Warning 

It is illegal to send messages to wildcard subject names. Although rvcm_Send ( ) does 
not prevent the user from sending illegally to wildcard subjects, the results are 
unpredictable. 

25 Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


subject 


Send the message to this subject name or 




inbox. 


msgType 


Datatype of the message data. 
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msgSize 


Length of the data (in bytes). 


Tnsg 


Location of the data to send. 


timeLimit 


Retain the message in the ledger, and 
continue attempts at delivery either until 
completion of delivery or until this time limit 
(in seconds) expires. 

Zero is a special value, indicating no time 
limit; the message remains in the ledger until 
delivery is complete to all certified 
listeners. 

A non-zero value less than 60 seconds adds 
no advantage over ordinary reliable message 
delivery, since rvd retains and retransmits 
messages for 60 seconds. 


sequenceNum 


This location receives the sequence number 
of this message. 



Errors 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call 




completed successfully. 
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RVCM ERR INVALID SESSION 


The function received a 




session argument that is 




not a valid rv_Session 




(for example, NULL, or 




a session that has 




already terminated). 


RVTM FRR R An ARfi 


The function received an 




illegal argument. 




rvcm_Send () or 




rvcm_SendWithReply () 




received either a NULL 




subject, or a NULL 




sequence number pointer 


RVCM ERR NO MEMORY 


The function could not 




complete because the 




operating system denied 




its request to allocate 




storage. 


RVCM_ERR_BAD_SUBJECT 


rvcmSend () or 




rvcm_SendWithReply () 




received an ill-formed 




subject name. 




Either it contained too 




many total characters, 




too many characters in 




an element, or too many 




elements. 
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RVCM_ERR_SESSION_NOT_ENABLED 


"Z~~~r — ; 1 

Toe function received a 




session that is not 




enabled for delivery 




tracking. 


Coding Example 




int timejimit - 600; /♦ 600sec = lOmin */ 





cm_err - rvcm_Scnd(sess, subject, type, sizeoflmsg), msg, 

timejimit, &seq_no); 
if (crnerr — RVCM_OK) 

rprintf((stderr, "Sent sequence num %d\n\ seq_no); 

10 else 

fprintffstderr, "Error while sending certified message: %s\n", 
rvcm_ErrorText (sess, cm err) ); 

See Also 

15 rvcm_Seq, above 

rvcm_SendWithReply(), below. 
rvcni_SendV/ithRepryO 

Function 

20 

Declaration 

rvcni_Error rvcm_SendWithReply ( 



rvSession 


session, 


rv_Name 


subject, 


rv_Name 


replyName, 


rvms g_Type 


msgType, 


rvmsgSize 


msgSize, 


rvmsgData 


msg, 



unsigned long timeLimit, 



50 

SUBSTTTUTl SHEET (RULE 28) 



CA 02313039 2000-02-14 
WO 99*9490 PCT/US9OT7I IS 

rvcm_Seq* sequenceNum 

Purpose 

Send a labeled request message, and track delivery to cooperating listeners. A request 
5 message includes a reply name as a return address for response messages. 

Remarks 

This function is parallel to rv_SendWithReply (). Notice that its signature includes 
two additional parameters, timeLimit and sequenceNum. 

10 

The reply name must be the subject name of an open listening endpoint (either 
broadcast or inbox). An application may receive zero, one or several responses to a 
request message. Before the user calls rvcm_SendWithReply ( ) the user must ensure 
that the appropriate application components are listening to the reply name. 

15 

rvcm_SendWithReply ( ) is a non-blocking function. It returns immediately, and the 
callback function receives any replies asynchronously. A reply is not guaranteed (for 
example, if the receiver does not send any reply). 

20 Use timeLimit to specify the duration of the message, the system retains the message 
in its ledger until either it receives delivery confirmation from all cooperating 
listeners, or the UmeLimit expires. If the time limit expires before delivery is 
complete, the system removes the message from the ledger, and generates a 
DELIVERY.F AILED advisory message listing the cooperating listeners that did not 

25 confirm delivery of the message. 

A timeLimit value greater than 60 seconds is recommended, since the domain holds 
messages for 60 seconds. 

30 rvcrnJendWithReptyO 

rvcm_SendWithReplyO labels the message with the name of the delivery-tracking 
session and a sequence number. rvcm_SendWithReplyO passes the sequence number 



51 

SUBSTITUTE SHEET (RULE 28) 



CA 02313039 2000-02-14 
W0 99*MM PCT/USWI7115 
back to the caller in its sequenceNum parameter (the user can use this number for 
auditing)>. 

Each sending session maintains a separate sequence for each subject it sends. As a 
5 result, receivers can uniquely identify each labeled message by the three data callback 
arguments subject, senderName and sequenceNum. 

When msg has self-evident length, the user may supply zero for msgSize (the system 
computes the actual size automatically). Types with self-evident size are 
10 RVMSG.RVMSG, RVMSG_STRING (when the string is NULL-terminated) and 
RVMSG_ENNCRYPTED. All other types require an explicit size argument in this 
call. 

rvcm_SendWithReply() copies its arguments. After rvcm_SendWithRepIy() returns, 
1 S the user may free or reuse the storage (for example, a message buffer). 

Warning 

It is illegal to send messages to wildcard subject names. Although the function 
rvcm_SendWithReplyO does not prevent the user from sending illegally to wildcard 
20 subjects, the results are unpredictable. 

Parameters 



Parameter 


Description 


Session 


A delivery-tracking session. 


Subject 


Send the message to th 


is subject nai 


me or 




inbox. 
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ReplyName - 


Subject name for replies to this request 
message (similar to a return address on a 
letter, and delivered to receiving applications 
in the rcplyName argument of the callback 
function). 

The reply name may be an inbox or subject 
name. Before calling rvcm SendWithReplyQ 
ensure that a listening endpoint is already 
open for the reply name. 


MsgTypc 


Datatype of the message data. 


MsgSize 


Length of the data (in bytes). 


Msg 


Location of the data to send. 


timeLimit 


Retain the message in the ledger, and continue 
attempts at delivery either until completion of 
delivery or until this time limit (in seconds) 
expires. 

Zero is a special value, indicating no time 
limit: the message remains in the ledger until 
deliver, is complete to ail certified listeners. 

A non-zero value less than 60 seconds adds 
no advantage over ordinary reliable message 
delivery, since rvd retains and retransmits 
messages for 60 seconds. 


sequenceNum 


This location receives the sequence number of 
this message. 



Errors 
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RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session argument 
that is not a valid rv Session (for 
example, NULL, or a session that has 
already terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal argument. 
rvcm_Send() or rvcm SendWithReply() 
received either a NULL subject, or a 
NULL sequence number pointer. 


RVCM_ERR_NO_MEMORY 


The function could not complete because 
the operating system denied its request to 
allocate storage. 


RVCM_ERR_BAD_SUBJECT 


rvcm_Send() or rvcm_SendWithReply() 
received an ill-formed subject name. 
Either it contained too many total 
characters, too many characters in an 
element, or too many elements. 


RVCM_ERR_SESSION_NOT_ENA 
BLED 


The function received a session that is not 
enabled for delivery tracking. 



Coding Example 

cmerr = rvcm SendWithRepry(sess, subject, reply, 
5 type, sizeof(msg } , msg, 

600, &seq_no); 

(cm_err = RVCM_OK) 

fprintf(stdeiT, "Sent sequence num %d\n", seq_no); 

else 

1 0 fprintf{stderr, "Error while sending certified message: %s\n", 

rvcm_ErrorText (sess, cm_err) ); 
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See Abo - 

rvcm_Seq, page 203; and 
rvcm_ScndWithReply(), above. 

5 

rvcm_Add ListenerO 

Function 

Declaration 

1 0 rvcmError rvcm_AddListener ( 
rvSession session, 
rvName name, 
rvNamc subject ) 

15 Purpose 

Pre-registcr an anticipated listener. 

Remarks 

Some sending applications can anticipate requests for certified delivery-even before 
20 the listening applications begin running. In such situations, the sender can pre- 
register listeners, so the system begins storing outbound messages in the sender's 
ledger, when the listener requests certified delivery, it receives the backlogged 
messages. 

25 If the correspondent with this name already receives certified delivery of this subject 
from this sender session, then rvcm_AddListenerO has no effect. 

If the correspondent with this name is disallowed, then rvcm_AddListener() returns an 
error. The usercan call rvcm_AllowListener() to supersede the effect of a prior call to 
30 rvcm_DisallowListenerO; then call rvcm_AddListener() again. 

Parameters 
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Parameter 


Description 


session 


A delivery-tracking session. 


subject 


Anticipate a listener for this subject. 


name 


Anticipate a listener from a correspondent with this 
reusable name. 



rvcm_AddListenerQ 



5 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a sess ion 
argument that is not a valid rv_session 
(for example, NULL, or a session that 
has already terminated). 


RVCM_ERR_BAD_SESSION_NAM 
E 


The function received an ill-formed 
reusable name. 


RVMC_ERR_BAD_ARG 


The function received an illegal 
argument. 

rvcm_AddListenerO received a NULL 
listener name. 


RVCM_ERR_SESSION_NOT_ENA 
BLED 


The function received a session that is 
not enabled for delivery tracking. 
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RVCM_ERR_BAD_SUBJECT 


The function received an ill-formed 
subject name. 

Either it is NULL, or contained too 
many total characters, too many 
characters in an element, too many 
elements, or an illegal prefix. 


RVCM_ERR_DISALLOWED_LIST 
ENER 


rvcm_AddListener() cannot add this 
listener because it is disallowed. First 
call rvcm_AllowListener(). 



Coding Example 

cm_err = rvcm_AddListener(sess, "LISTENER! 7". subject); 
if(cm_err != RVCM_OK) 
5 { 

fprintf(stderr, "Can't add CM listener:\n %s\n", 

rvcm_ErrorText(scss, cmerr)); 
exit(-l); 
} 

10 

See Abo 

rvcm_RemoveListener(), below. 



15 rvcm_RemoveListenerO 

Function 

Declaration 

20 rvcm_Error rvcm_RemoveListencr ( 
rvSession session, 

rv_Name name, /* listening correspondent name */ 

rvName subject ) 
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Purpose 

Unregtsttr a specific listener at a specific correspondent, and free associated storage 
in the sender's ledger. 



5 Remarks 

This function cancels certified delivery of the specific subject to the correspondent 
with this name. The listening correspondent may subsequently re-register for certified 
delivery of the subject. (In contrast, rvcm_DisallowListenerO cancels certified 
delivery of all subjects to the correspondent, and prohibits re-registration.) 

10 

Senders usually call this function when the ledger item for a listening correspondent 
has grown very large. Such growth indicates that the listener is not confirming 
delivery, and may have terminated. Removing the listener reduces the ledger size by 
deleting messages stored for the listener. 

15 

When a sending program calls this function, certified delivery software in the sender 
behaves as if the listener had closed the endpoint for the subject. The sending program 
deletes from its ledger all information about delivery of the subject to the 
correspondent with this name. The sending program receives a REGISTRATION. 
20 CLOSED advisory, to trigger any operations in the callback function for the advisory. 



If the listening correspondent is available (running and reachable), it receives a 
REGISTRATION.NOT_CERTIFIED advisory, informing it that the sender no longer 
certifies delivery of the subject. 

If the correspondent with this name does not receive certified delivery of the subject 
from this sender session, . then rvcm_RemoveListener() returns 
RVCM_ERR_BAD_SUBJECT. 
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Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


subject 


Cancel certified delivery of this subject. 


name 


Cancel certified delivery of the subject to the 
correspondent with this name. 



5 Errors 



RVCMJERR Code 


Indicates 


RVCM_OK 


No error. The call completed 




successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 




argument that is not a valid 




rv Session (for example, NULL 




Or a session that has already 




terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 




argument. 




rvcm_RemoveListenerO received 




a NULL listener name or NULL 




subject; or the sender does not 




certify delivery of the subject to 




the listener. 
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RVCM_ERR_SESSION_NOT_ENA 


The function received a session 


BLED ~ 


that is not enabled for delivery 




tracking. 


RVCM FRR Din ci id rp/^T 


The function received an in- 




formed subject name. 




Either it is NULL, or contained 




too many total characters, too 




many characters in an element, 




too many elements, or an illegal 




prefix. 




rvcm_RemoveListenerO received 




a subject containing wildcard 




characters; or the sender has not 




sent certified messages on this 




subject. 


RVCM_ERR_DISALLOWED_LIST 


rvcmRemoveListenerO cannot 


ENER 


cancel certified delivery to this 




listener because the listener is 




disallowed. 



Coding Example 



cm_err = rvcm_RemoveListener(sess, listener, subject); 
5 if(cm_eir !- RVCM_OK) 
{ 

fprintf(stderr, "Can't remove CM listener:\n %s\n", 

rvcm_ErrorText(sess, cm_err)); 
exit(-l); 
10 } 

See Also 

rvcm_AddListenerO, above; and 
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rvcm_Disal loyyListenerO, below. 

rvcm_DisallowLiatenerO 

5 Function 

Declaration 

rvcm_Error rvcm_DisaIlowListener ( 
rvSession session, 
10 rvName name) 

Purpose 

Cancel certified delivery to all listeners at a specific correspondent Deny subsequent 
1 5 certified delivery registration requests from those listeners. 

Remarks 

Disallowed listeners still receive subsequent messages from this sender, but delivery 
is not certified. That is: 

20 

■ The listener receives a REGISTRAT10N.NOT_CERTIFlED advisory, 
informing it that the sender has cancelled certified delivery of all subjects. 

■ If the sender's ledger contains messages sent to the disallowed listener (for 
25 which this listener has not confirmed delivery), then the system removes those 

ledger items, and does not attempt to redeliver those messages. 

■ The system presents subsequent messages (from the cancelling sender) to the 
listener with sequence number zero, to indicate that delivery is not certified. 

30 Senders can promptly revoke the acceptance of certified delivery by calling 
rvcm_DisallowListener() within the callback function that processes the 
REGISTRATION.REQUEST advisory. 
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This function disallows a correspondent by name. If the correspondent terminates, 
and^ another process instance (with the same reusable name) takes its place, the new 
process is still disallowed by this sender. 

5 To supersede the effect of rvcm_DisallowListenerO, call rvcm_AllowListener(). 

Parameters 



Parameter 


Description 


session 


A delivery-tracking session 


name 


Cancel certified delivery to listeners at the 
session with this name. 



10 

Errors 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 




successfully. 


RVCM_ERR_INVALID_SESSIO 


The function received a session 


N 


argument that is not a valid 




rv_Session (for example, NULL< 




or a session that has already 




terminated). 


RVCM_ERR_BAD_SESSION_N 


The function received an ill- 


AME 


formed reusable name. 
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RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. 

rvctn_DisallowListener() received 
a NULL listener name. 


RVCM_ERR_SESSION_NOT_E 
NABLED 


The function received a session 
that is not enabled for delivery 
tracking. 



Coding Example 

cm err = rvcm_DisallowListener(sess. "LISTI NI-RJ 7"); 
5 if(cm_err != RVCM_OK) 
{ 

fprintf(stderr, "Can't disallow CM listener: n %s\n". 

rvcm_ErrorText(sess, cm_err)); 
exh(-l); 
10 } 

rvcm_AllowListenerO 

Function 

15 

Declaration 

rvcm_Error rvcm_AllowListener ( 

rv_Session session, 
20 rv_Name name ) 

Purpose 

Invite the named receiver to reinstate certified delivery for its listeners, superseding 
the effect of any previous calls to rvcm_DisallowListener(). 

25 
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Remarks 

Upon receiving the invitation to reinstate certified delivery, the system at the listening 
program automatically sends new registration requests. The sending program accepts 
these requests, restoring certified delivery. 

5 

Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


name 


Accept requests for certified delivery to listeners at the 
session with this name. 



RVCMERR Code 


Indicates 


RVCM.OK 


No error. The call completed 
successfully. 


RVCM_ERRJNVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_Session (for example, NULL, 
or a session that has already 
terminated). 


RVCM_ERR_BAD_SESSION_NAM 
E 


The function received an ill- 
formed reusable name. 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. rvcm_AllowListenerO 
received a NULL listener name. 
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RVCM_ERR_SESSION_NOT_ENA 


The function received a session 




that is not enabled for delivery 




tracking. 



Coding Example 

cm_err « rvcm_AllowLUtener(scss, "LISTENER_17"); 
if(cm_err != RVCM_OK) 
5 { 

fprintf(stderr, "Can't allow CM listenenln %sin", 

rvcm_ErrorText(sess, cm_crr)); 
exit(-l); 
} 

10 

rvcm_NoAatoConfirm() 

Function 

IS Declaration 

rvcm_NoAutoConfirm( 

rv_Session session, 
rvcm_ListenId listenid); 

20 Purpose 

Override automatic confirmation of delivery for this listening endpoint. 
Remarks 

The default behavior of certified listeners is to automatically confirm message 
25 delivery upon return from the data callback function (see rvcm_Callback, above). 
This call selectively overrides this behavior for this specific listening endpoint. (This 
call does not affect other listening endpoints.) 

By overriding automatic confirmation, the listener assumes responsibility for 
30 explicitly confirming each inbound certified message by calling rvcm_Confirm(). 
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Consider "overriding automatic confirmation when processing inbound messages 
involves asynchronous activity, such as computations in other threads, database 
queries, or additional network communications. 

5 

No method exists to restore the default behavior, reversing the effect of this function. 
Parameters 

Parameter 

10 



Parameter 


Description 


session 


A delivery-tracking session. 


iistenld 


Override automatic confirmation for inbound certified 
messages to this listening endpoint. 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALlD_SESSIO 
N 


The function received a session 
argument that is not a valid rv Session 
(for example, NULL, or a session that 
has already terminated). 


RVCM_ERR_NONEXISTENT_I 
D 


rvcm_NoAutoConfirmO received an 
unusable Iistenld pointer-either NULL, 
or it points to something other than an 
rvcm_ListenId, or it has already been 
closed. 
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See Also 

rvcm_Caiiback above, and 
rvcm_€onfirmO, below. 

5 rvcm_ConfirmO 

Function 

Declaration 

rvcm_Confinn() 

10 

rvSession session, 
rvcm_ListenId listenerld, 
rvName senderName. 
rvcm_Seq sequenceN umber) 

15 

Purpose 

Confirm delivery of a certified message. 
Remarks 

20 Use this function only in programs that override automatic confirmation. 

The triplet of subject name, sender and sequence number uniquely identifies each 
certified message. The subject name is already stored in the listening endpoint. The 
other two components—sender and sequence number-are explicit parameters of this 
25 function. 



Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


listenld 


Confirm delivery of a message by this listening 




endpoint. 
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senderName . 


Confirm delivery of a message from the sender with 
this correspondent name. 


sequenceNumber 


Confirm delivery of the message with this sequence 
number. 



Errors 



RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv Session (for example, NULL, or 
a session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. 

rvcm_Confirm( ) received a 
sequence number argument that is 
out of range. 


RVCM_ERR_ID_CONFIRM_CON 
FLICT 


rvcm_Confirm() received a listenld 
that automatically confirms 
delivery. rvcm_Confirm() is only 
valid after overriding automatic 
confirmation with 
rvcm_NoAutoCon firmQ. 
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RVCM_ERR;_NONEXI STENTJD 


rvcm_Confirm() received an 
unusable listenld pointer-either 
NULL, or it points to something 
other than an rvcmJListenld, or it 
has already been closed. 


RVCM_ERR_NONEXI STENT_PU 
BLISHER 


rvcm_confirm() received a 
senderName argument that is not 
recognized as the name of a 
certified sender. | 



See Abo 

rvcm Callback; and rvcm_NoAutoConfirm(). above. 



5 rvcm_ReviewLedgcr() 

Function 



Declaration 

rvcmError rvcm_ReviewLedger 

10 rv_Session session, 

rv_Name subject, 

rvcmReviewCallback reviewCallbackFn 

rvOpaque closure Arg ); 



15 

Summarize the delivery status of messages in the ledger, 



Remarks 

The callback function receives one message for each matching subject stored in the 
20 ledger. For example, when rvcm_ReviewLedgerO receives FOO. * as its subject 
argument, it calls the callback function separately for these matching subjects-once 
for FOO.BAR, once for FOO.BAZ, and once for FOO.BOX. 
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However, if the callback function returns non-NULL, then rvcm_ReviewLedger() 
returns-inaniediately. 

If the ledger does not contain any matching items, rvcm_ReviewLedgerO returns 
5 normally without calling the callback function. 

For information about the content and format of the callback messages, see 
rvcm_ReviewCallback, below. 

10 Parameters 



Parameter 


Description 


session 


A delivery-tracking session. 


subject 


Review ledger items with this subject 

If this subject contains wildcard characters ("*" 
or ">"), then review all items with matching 
subject names. The callback function receives a 
separate message for each matching subject in 
the ledger. 


reviewCallbackFn 


This function receives the review messages. 


closureArg 


Pass this closure argument to the callback 
function. This argument must be a pointer, but it 
can point to any type of data. It contains any 
information needed by the callback function, the 
system treats this argument as an opaque 
closure, forwarding it to the callback function 
without accessing its value. 



Errors 
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RVCM ERR Code 


Indicates 


KVCMOK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_Session (for example. NULL, or 
a session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. rvcm_ReviewLedgerO 
received a NULL subject name or a 


RVCM_ERR_NO_MEMORY 


The function could not complete 
because the operating system denied 
its request to allocate storage. 


RVCM_ERR_SESSION_NOT_EN 
ABLED 


The function received a session that 
is not enabled for delivery tracking. 



Coding Example 

fprintf(stdout,"\nLedger review for subject •%•>'. %d:\n". 
subject, reviewMax); 

5 

/*** See rvcm_ReviewCallback example function, below. *••/ 
cm_err - rvcmJReviewLedger (session, rv_Name)subject, 

myReviewLedgerCallback, 
(rv_Opaque)&reviewMax); 

10 if ( cm_err !- RVCM_OK) 

{ 

fprintf(stderr, "Review ledger failed for '%s':\n\t%s\n", 
subject, rvcm_ErrorText(sess, cm_err)); 

} . 
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SeeAta^ 

rvcmJleviewCallback, above. 

5 rvem.ReviewCaUback 

Datatype 



Declaration 

void* rvcmReviewCallback ( 

rvSession session, 
rv_Name subject, 
rvmsg_Msg msg, 
rv_Opaque closure Arg ) 



IS Purpose 

rvcm_ReviewCallback is the function type of callback functions for reviewing the 
ledger. Applications define functions of this type to process the summary messages 
from rvcm_ReviewLedgerO. 

20 Remarks 

rvcm_ReviewLedger{) callS this callback once for each matching subject in the 
ledger. 

To continue reviewing the ledger, return NULL from this callback function. To stop 
25 reviewing the ledger, return non-NULL from this callback function; 
rvcm_ReviewLedgerO returns immediately. 



30 
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Parameter 


Description j 


session 


This parameter receives the current session. 


subject 


This parameter receives the subject name 
that the message summarizes. 


msg 


This parameter receives a summary message 
describing the delivery status of messages in 
the ledger. The table below describes the 
fields of the summary message. 


closure Arg 


This parameter receives a closure argument, 
which the application supplied when it called 
rvcm_ReviewLedger(). This argument is a 
pointer, but it can point to any type of data. 
It contains any information needed by 
the callback function. The system treats this 
argument as an opaque closure, forwarding it 
to the callback function without accessing 
its value. 


Message Content 




Field Name 


Description 


subject 


The subject that this message summarizes. 
This field has datatype RVMSG_STRING. 


seqno_last_sent 


The sequence number of the most recent 
message sent with this subject name. 

This field has datatype RVMSG_UTNT. 
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total_msgs - 


The total number of messages with this 
subject name. This field has datatype 
RVMSG_UINT. 


total_size 


The total storage (in bytes) occupied by all 
messages with this subject name. 

If the ledger contains ten messages with this 
subject name, then this field sums the 
storage space over all of them. I 

This field has datatype RVMSG_UINT. 


listener 


Each summary message can contain one or 
more fields named listener. Each listener 
field contains a nested submessage with 
details about a single registered listener. 
This field has datatype RVMSGJRVMSG. 


listener, name 


Within each listener submessage, the name 
field contains the name of the delivery- 
tracking listener. 

This field has datatype RVMSG_STRING. 


listener.Iastconfirmed 


Within each listener submessage, the 
last_confirmed field contains the sequence 
number of the last message for which this 
listener confirmed delivery. 

This field has datatype RVMSG UINT. 



Coding Example 



/*** See rvcm_ReviewLedger() example call, above. ***/ 
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royRevie\vLedgerCallback(rv_Sessionsess, 

' rv_Name subject, 

rvmsg_Msg msg, 
rv_Opaque arg) 

5 { 

int * count = (int*) arg; 

/* Print the ledger item. */ 

printf("\nLedger item for '%s':\n", subject); 

rvmsg_Print(sess, msg, NULL); 
0 printf("\n"); 

if ( * count ) 

{ 

(*count)— ; 
5 if(( *count)>0); 
{ 

/* When count reaches zero, stop. Return from ncm ReviewLedger() */ 
return((void*)sess); 

} 

0 } 

return(NULL); /* Otherwise, continue to the next item. *•' 
See Also 
5 rvcm_ReviewCallback 

rvcm_ReviewLedger(), above. 
rvcm_SyncLedgerFile() 

0 

Function 
Declaration 

rvcm_ErroT rvcm_SyncLedgerFile (rv_Session session); 
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Purpose^ 

Synchronize the ledger file to its storage medium. 
5 Remarks 

When this function returns, the session's current state is safely stored in the ledger 
file. 

Delivery-tracking sessions that use synchronous ledger files need not call this 
10 function, since the current state is automatically written to the file system before 
returning. 

Parameters 



15 



Parameter 


Description 


session 


Synchronize the ledger file associated with this 
delivery-tracking session. 
1 — _l 



Errors 



RVCM Error Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_Session (for example, NULL, or 
a session that has already 
terminated). 


RVCM_ERR_SESSION_NOT_EN 


The function received a session that 


ABLED 


is not enabled for delivery tracking. 
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RVCM_ERR_FILE_IO_ERROR 



rvcm_SyncLedgerFile() 
encountered an error while writing 
the ledger file. 



See Also 

rvcm_Enable(), above. 



5 rvcmError 



Datatype 



rvcm_Error iS art enumerated type for error codes. Table A2 lists the possible 
10 rvcm_Error values. The user can use the function rvcm_ErrorText() to convert 
rvcm_Error message codes to descriptive text. For more information, see 
rvcm_ErrorText() on page 244. 



Table A2: Enumerated Values of rvcm_Error 

15 



RVCM Error Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_IN1T_FAILURE 


rvcm_EnableQueue() could not 
initialize either the certified delivery 
or fault tolerance components upon 
which it depends. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_Session (for example, NULL, or a 
session that has already terminated). 


RVCM_ERR_BAD_SESSION_NA 
ME 


The function received an ill-formed 
reusable name. 
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RVCM Error Code 


Indicates 




rvcm_ListenSubject() received either 
a NULL callback function, or a 
NULL listenid pointer. 




rvcm_ListenInbox() received either a 
NULL inbox name pointer, a NULL 
callback function, or a NULL listenid 
pointer. 




rvcm_DisallowListener() received a 
NULL listener name. 




rvcm_AllowListener() received a 
NULL Listener name. 




rvcm_AdclListener() received a 
NULL listener name. 




rvcm_RemoveListener() received a 
NULL listener name or NULL 
subject; or the sender does not certify 
delivery of the subject to the listener. 




rvcmSendO or 
rvcm_SendWithReply() received 
either a NULL subject, or a NULL 
sequence number pointer. 




rvcm_ReviewLedger() received a 
NULL subject name or a NULL 
review callback function. 
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RVCM Error Code 


Indicates 




rvcm_Confirm() received a sequence 
number argument that is out of range. 


RVCM_ERR_NO_MEMORY 


The function could not complete 
because the operating system denied 
its request to allocate storage. 


RVCM_ERR_BAD_SUBJECT 


rvcm_Send( ). 

rvcm_SendWithReply() or 
rvcm_ListcnSubject() received an in- 
formed subject name. 

Either it is NULL, or contained too I 
many total characters, too many 
characters in an element, too many 
elements, a wildcard character, or an 
illegal prefix. 

rvcm_RemoveLisiener() received a 
subject containing wildcard 
characters: or the sender has not sent 
certified messages on this subject. 


RVCM_ERR_ID_CONFIRM_CON 
FLICT 


rvcm_Confirm() received a listenid 
that automatically confirms delivery. 
rvcm_confirm() is only valid after 
overriding automatic confirmation 
with rvcm_NoAutoConfirm ( ). 


RVCM_ERR_NONEXISTJENT_ID 


rvcm_Close(), 

rvcmNoAutoConfirm (), or 
rvcm_Confirm() received an 
unusable listenid pointer-either 
NULL, or it points to something 
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RVCM Error Code 


Indicates 




other than an rvcm_Listenld, or it has 
already been closed. 


RVCM_ERR_DUPLICATE_SUBJ 
ECT 


rvcm_ListenSubject() can open at 
most one listening endpoint per 
subject; it cannot open a second 
listening endpoint for this subject. 


RVCM_ERR_NONEXISTENT_PU 
BLISHER 


rvcm_Confirm() received a 
senderName argument that is not 
recognized as the name of a certified 
sender. 


RVCM_ERR_DISALL0WED_L1S 
TENER 


rvcm_AddListener() cannot add this 
listener because it is disallowed. First 
call rvcm_AllowListener(). 

rvcm_RemoveListener() cannot 
cancel certified delivery to this 
listener because the listener is 
disallowed. 


RVCM_ERR_SESSION_ALREAD 
YENABLED 


rvcm_Enable() received a session 
that is already enabled for delivery 
tracking. It is illegal to enable a 
session more than once. 


RVCM_ERR_SESSION_NOT_EN 
ABLED 


The function received a session that 
is not enabled for delivery tracking. 


RVCM_ERR_LEDGER_NAME_C 
ONFLICT 


rvcm_Enable() received NULL as the 
name parameter, but a non-NULL 
value as the ledgerFile parameter. 


RVCM_ERR_PARAMETER_CON 
FLICT 


The function received conflicting 
values for parameters. 

rvcm_Enable() received RV FALSE 
as its requireOldMsgs parameter, and 
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RVCM Error Code 


Indicates 




NULL as its name parameter. A non- 
reusable name implies a transient 
correspondent, which cannot have 
backlog messages. 


RVCM_ERR_FILE_IO_ERROR 


rvcm_Enable() encountered an error 
while opening the ledger file. For 
example, an explicitly named 
directory does not exist. 

rvcm_SyncLedgerFile() encountered 
an error while writing the ledger file. 


RVCM_ERR_FILE_NO_PERMISS 
ION 


File access privileges are insufficient 
for rvcm_Enable ( ) to open the 
ledger file. fl 


RVCM_ERR_FILE_NOT_LEDGE 
R_OWNER 


The reusable name recorded in the 
file differs from the name of this 
session. ryere_Enable ( ) stopped 
reading the file. 


RVCM_ERR_CORRUPT_LEDGE 
R_FILE 


The ledger file is corrupt. 
rvcm_Enable() could read only part 
of the ledger file into process-based 
memory. Some information may be 
lost. 



See Also 

rvcm_ErrorText(), below. 
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APPENDIX B: Distributed Queues (Programming Details for C Programmers) 

This Appendix A provides programming details for C programmers wishing to 
implement Certified message Delivery. The Appendix provides, in Table Al, an 
5 overview listing of Certified's messaging Deliver Datatypes and Functions. Each 
Datatype or Function is then described in greater detail with Cross-references to 
related Datatypes or Functions. 



As described above, Applications can use distributed queues for certified delivery to 
10 one ofn listeners (queue member sessions). These distributed queue functions are 
typically used in combination with certified message delivery. 



Distributed Queue CAPI 

15 The following Table BA summarizes the datatypes and functions in the distributed 
queue C API. 



Table Bl : Distributed Queues: Dataty yes and Functions 



Item 


Description 


Page 


rvcm_EnableQueue() 


Enable a session as a distributed 
queue member 


248 


rvcm_rvcm_SetQueueAcceptTime 
0 


Set the queue time limit for task 
acceptance. 


251 


rvcm_QueueAcceptTime() 


Return the queue time limit for 
task acceptance. 


253 


rvcm_SetQueueCompleteTime() 


Set the queue time limit for task 
completion. 


255 


rvcm_QueueCompleteTime() 


Return the queue time limit for 
task 

completion. 


257 
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Item 


Description 


Page 


rvcm_SetQueueListenerWeight() 


Set the listener weight of a 
queue member. 


261 


rvcm_QueueListenerWeight() 


Return the listener weight of a 
queue member. 


261 


rvcm_SetQueueListenerTasks() 


Set the listener task capacity of a 
queue member. 


263 


rvcm_QueueListenerTasks() 


Return the listener task capacity 
of a queue member. 


266 


rvcmError 


Datatype. Enumerates error 
codes for the certified message 
deliver) API and distributed 
queue API. 


239 


rvcm_ErrorTest() 


Return a text string describing 
an error code 


244 



rvcm_EnableQueue() 

Function 



5 Declaration 

rvcm_Error rvcm_EnableQueue ( 

rv_Session session 
rv Name name, 
unsigned long schedulerWeight, 
10 unsigned long schedulerHeartbeat, 

unsigned long schedulerActivation ); 

Purpose 

Enable a session for certified message delivery as part of distributed queue for one-of- 
15 n certified delivery. 

Remarks 
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Each member of a distributed queue listens for the same subjects— yet even when n 
members listen, for each inbound message (or task), exactly one member processes 
the message. 

5 Programs must call rvcm_EnableQueue() before any other calls related to distributed 
queues or certified listening. 

Once a session becomes a queue member, it cannot resign membership except with 
rv_Term(). 

10 

Queue Member Roles 

Each distributed queue member session has two distinct roles-as a listener, and as a 
potential scheduler. 

15 In the listener role, queue member sessions support a limited subset of certified 
delivery calls: rvcm_ListenSubject(), rvcm_NoAutoConfirm() and rvcm_Confirm(). 
Queue member sessions do not support any other certified delivery calls (in particular, 
calls associated with sending certified messages). However, they do support all 
standard system calls (for example. rv SendO). 

20 

System fault tolerance software maintains exactly one active scheduler in each queue: 
if the scheduler process terminates, another member assumes the role of scheduler. 
The queue member session in the scheduler role assigns inbound tasks to listeners in 
the queue. (A scheduler can assign tasks to its own listener component, but only does 



so when all other listeners an 


busy.) 




Parameters 






Parameter 


Description 


session 


The call enables this session. 






Before this call, the session mi 
enabled for delivery tracking. 

84 
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Paramejer 


Description 


name 


The session becomes part of the distributed 
queue with this 
reusable name. 


schedulerWeight 


Weight represents the ability of this session to] 
fulfill the role of scheduler, relative to other 
members of the same queue. The queue 
members use relative scheduler weight values 
to elect one member as the scheduler; 
members with higher scheduler weight take 
precedence. 

Acceptable values range from I to 65535 (even 
though the parameter is declared as an 
unsigned long). 


schedulerHeartbeat 


The scheduler session sends heartbeat 
messages at this interval (in milliseconds). 

All sessions in the queue must specify the 
same value for this parameter. Acceptable 
values are the unsigned 32-bit integers (except 
zero). 


schedulerActivation 


When the heartbeat signal from the scheduler 
has been silent for this interval (in 
milliseconds), the queue member with the 
greatest scheduler weight takes its place as the 
new scheduler. 

All sessions in the queue must specify the 
same value for this parameter. Acceptable 
values are unsigned 32-bit integers (except 
zero). 
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RVCM_ERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv_session (for example, NULL, or a 
session that has already terminated). 


RVCM_ERR_SESSION_ALREAD 
YENABLED 


rvcm_Enable() received a session 
that is already enabled for delivery 
tracking. It is illegal to enable a 
session more than once. 


RVCM_ERR_NO_MEMORY 


The function could not complete 
because the operating system denied 
its request to allocate storage. 


RVCM_ERR_INIT_FAILURE 


rvcm_EnableQueue() could not 
initialize either the certified delivery 
or fault tolerance components upon 
which it depends. 



See Also 

rvcm_Enable(), Appendix A 
5 rvcm_ListenSubjectO, Appendix A 

rvcm SetQueueAcceptTimeO 

Function 

10 Declaration 

#define DEFAULT_ACCEPT_TIME (0) 

rvcm_Error rvcmSetQueueAccepCTime ( 
rv_Session session, 
1 5 unsigned long acceptTime ); 
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Purpose "~ 

Change the accept time parameter of a queue member session. 
5 Remarks 

When this session, acting as the scheduler, assigns a task to a listener (another queue 
member session), it sets a timer with this length (in milliseconds). If the timer elapses 
before the scheduler receives acceptance from the listener, the scheduler reassigns the 
task to another listener. 

10 

Zero is a special value, which specifies no limit on the acceptance time—that is, the 
scheduler does not set a timer, and does not reassign tasks. 

Enabling a session as a queue member tacitly sets its accept time parameter to - 

15 DEFAULT_ACCEPT_T1ME (zero). 

Parameters 



Parameter 


Description 


session 


A session in a distributed queue. 


acceptTime 


This value (in milliseconds) becomes the new time limit for 
acceptance of tasks. It must be less than the complete time 
parameter (unless the complete time is zero). 
1 — 



20 Errors 



RVCM_ERR Code 


Indicates II 


RVCM_OK 


No error. The call completed successfully. 1 
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RVCM_ERR Code 


Indicates 


RVCM_ERR_INVALID SESSION 


The function received a session argument 
that is not a valid rv session (for example, 
NULL, or a session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal argument. 


RVCM_ERR_SESSION_NOT_ENAB 
LED 


The function received a session that is not 
enabled for delivery tracking. 



See Also 



vcm_QueueAcceptTime(). below 

5 

rvcm_QueueAcceptTime() 

Function 

10 Declaration 

#define DEFAULT_ACCEPT_TIME (0) 

rvcm_Error rvcm_QueueAcceptTime ( 

15 rvSession session, 

unsigned long* acceptTime ); 



Purpose 

Extract the accept time parameter of a queue member session. 
Remarks 

When this session, acting as the scheduler, assigns a task to a listener (another queue 
member session), it sets a timer for the accept time (in milliseconds). If the timer 
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elapses before the scheduler receives acceptance from the listener, the scheduler 
reassigns the task to another listener. 

Zero is a special value, which specifies no limit on the acceptance time {the scheduler 
5 does not set a timer). 

Enabling a session as a queue member tacitly sets its accept time parameter to 
DEFAULT_ACCEPT_TIME (zero). 



1 0 Parameters 



Parameter 


Description 


session 


A session in a distributed queue. 


acceptTime 


This location receives the stored time limit (in milliseconds) for 
acceptance of tasks. 



Errors 



RVCM_ERR Code 


Indicates | 


RVCM_OK 


No error. The call completed successfully. II 



rvcm_Qz,QueueAcceptTime() 


RVCM_ERR Code 


Indicates 


RVCM_ERR_INVALID_SESSION 


The function received a 




session argument that is not a 




valid rv_session (for example, 




NULL, or a session that has 




already terminated). 


RVCMERRBADARG 


The function received an 




illegal argument. 
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RVCM_ERR_SESSION_NOT_ENABLED 



The function received a 
session that is not enabled for 
delivery tracking. 



See Also 

rvcm_SetQueueAccepcTimeQ, above 



5 

rvcm_SetQueueCompleteTime() 

Function 



Declaration 

1 0 tfdefine DEF AULT_COMPLETE_TIME (0) 
rvcm_Error rvcm_SetQueueCompleteTime ( 



rv_Session session, 
15 unsigned long completeTime ); 

Purpose 

Change the complete time parameter of a queue member session. 



Remarks 

20 When this session, acting as the scheduler, assigns a task to a listener (another queue 
member session), it sets a timer with this length (in milliseconds). If the timer elapses 
before the scheduler receives a completion message from the listener, the scheduler 
reassigns the task to another listener. 



25 Zero is a special value, which specifies no limit on the completion time (the scheduler 
does not set a timer). 



Enabling a session as a queue member tacitly sets its complete time parameter to 
DEFAULT_COMPLETE_TIME (zero). 

30 
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Parameters 



Parameter 


Description 


session 


A session in a distributed queue. 


completeTime 


This value (in milliseconds) becomes the new time 
limit for completion of tasks. It must be greater than 
the accept time parameter (unless the complete time 
is zero). 



I RVCM_ERR Code 


Indicates 


1 RVCM_OK 


No error. The call completed successfully. 



RVCM_ERR Code 


Indicates 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv session (for example, NULL, 
or a session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. 


RVCMERRSESSIONNOTENABL 
ED 


The function received a session 
that is not enabled for delivery 
tracking. 
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See Also 

rvcm_QueueCompleteTime(). below 

5 rvcm_QueueCompleteTime() 

Function 

Declaration 

#define DEFAULT_COMPLETE_TIME (0) 

10 

rvcm_Error rvcmQueueCompleteTime ( 

rv_Session session, 
unsigned long* completeTime ); 

15 

Purpose 

Extract the complete time parameter of a queue member session. 
Remarks 

20 When this session, acting as the scheduler, assigns a task to a listener (another queue 
member session), it sets a timer for the complete time (in milliseconds). If the timer 
elapses before the scheduler receives a completion message from the listener, the 
scheduler reassigns the task to another listener. 

25 Zero is a special value, which specifies no limit on the completion time (the scheduler 
does not set a timer). 

Enabling a session as a queue member tacitly sets its complete time parameter to 
DEFAULT_COMPLETE_TIME (zero). 

30 
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Parameter 


Description 


session 


A session in a distributed queue. 


completeTime 


This location receives the stored time limit 
(in milliseconds) for completion of tasks. 



5 Errors 



1 RVCM_ERR Code 


Indicates 


I RVCM_0K 


No error. The call completed successfully. 



RVCMJERR Code 


Indicates | 


RVCM_ERR_INVALID_SESSION 


The function received a 
session argument that is not 
a valid rv_session (for 
example, NULL, or a 
session that has already 
terminated). 


RVCM_ERR_BAD_ABG 


The function received an 
illegal argument. 


RVCM_ERR_SESS ION_NOT_ENABLED 


The function received a 
session that is not enabled 
for delivery tracking. 



10 See Also 

rvcm_SetQueueCompleteTime (), below 
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rvcm Error rvcm_QueueCompleteTime () 

Function 

5 Declaration 

#define DEFAULT_COMPLETE_TIME (0) 

rvcm_Error rvcm_QueueCompleteTime ( 

rvSession session, 
10 unsigned long* completeTime ); 

Purpose 

Extract the complete time parameter of a queue member session. 

15 

Remarks 

When this session, acting as the scheduler, assigns a task to a listener (another queue 
member session), it sets a timer for the complete time (in milliseconds). If the timer 
20 elapses before the scheduler receives a completion message from the listener, the 
scheduler reassigns the task to another listener. 

Zero is a special value, which specifies no limit on the completion time (the scheduler 
does not set a timer). 

25 

Enabling a session as a queue member tacitly sets its complete time parameter to 
DEFAULT_COMPLETE_TIME (zero). 



Parameters 




Parameter 


Description 


session 


A session in a distributed queue. 
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completeTime 


This location receives the stored time limit (in I 




milliseconds) for completion tasks. | 



Errors 



RVCM_ERR Code 


Indicates 


RVCM-ERR-INVALID-SESSION 


The function received a session 
argument that is not a valid 
rv Session (for example, NULL, 
or a session that has already 
terminated). 


RVCM-ERR-BAD-ARG 


The function received an illegal 
argument. 


RVCM_ERR_SESSION_NOT_ENABLED 


The function received a session 
that is not enabled for delivery 

tracking. 


RVCM_OK 


No error The call completed 
successfully. | 



5 See Also 

rvcm_SetQueueCompeteTime (), above. 



rvcm SetQueueListenerWeight() 

Function 

10 

Declaration 



#define DEFAULT_LISTENER_WEIGHT ( 1 ) 

1 5 rvcm_Error rvcm_SetQueueListener Weight ( 
rv_Session session, 
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unsigned long listenerWeight ); 

Purpose 

Change the listener weight parameter of a queue member session. 



When the scheduler receives a task, it assigns the task to the available listener with the 
greatest listener weight. 

10 

A listener is considered available unless either of these conditions are true: 

■ The pending tasks assigned to the listener exceed its task capacity. 

15 ■ The listener session is the scheduler. (The scheduler assigns tasks to its own 
listener 

only when no other listeners are available.) 

Enabling a session as a queue member tacitly sets its listener weight parameter to 
20 DEFAULT_LISTENER_ WEIGHT ( 1 ). 
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Parameters 





Description 


session 


A session in a distributed queue. 


listenerWeight 


This value becomes the new listener weight of 
the session. 



Errors 

5 



RVCM_ERR Code 


Indicates 


RVCM OK 


No error. The call completed 1 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a 
session argument that is not a 
valid rv_Session (for example, 
NULL, or a session that has 
already terminated). 


RVCM_ERR_BAD_ARG 


The function received an 
illegal argument. 


RVCM_ERR_SESSION_NOT_ENABLED 


The function received a 
session that is not enabled for 
delivery tracking. 



See Also 



rvcm_QueueListener Weight 0, below. 

10 

rvcm_QueueListenerWeight() 

Function 
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Declaration 

#define DEFAULT_LISTENER_WEIGHT (1) 

5 rvcm_Error rvcm_QueueListenerWeight ( 
rv_Session session, 
unsigned long* listenerWeight ); 

Purpose 

10 

Extract the listener weight parameter of a queue member session. 
Remarks 

1 5 When the scheduler receives a task, it assigns the task to the available listener with the 
greatest listener weight. 

A listener is considered available unless either of these conditions are true: 

20 ■ The pending tasks assigned to the listener exceed its task capacity. 

■ The listener session is the scheduler. (The scheduler assigns tasks to its own 
listener 

only when no other listeners are available.) 

25 

Enabling a session as a queue member tacitly sets its listener weight parameter to 
DEFAULT_LISTENER_WEIGHT (1). 

Parameters 

30 



| Parameter 


Description 


1 session 


A session in a distributed queue. 
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This location receives the current fl 
listener weight of the session. 



Errors 


RVCM_ERR Code 


Indicates 


RVCMOK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


I he function received a 
session argument that is not a 
valid rvSession )for 
example. NULL, or a session 
that has already terminated). 


RVCMERR BADARG 


1 he function received an 
illegal argument. 


RVCM_ERR_SESSION_NOT_ENABLEI) 


1 he function received a 
session that is not enabled for 
delivery tracking. 



5 See Also 

rvcmSetQueueListenerWeight (). above 



rvcmSetQueueListenerTasksO 



#defme DEFAULT_LISTENER_TASKS ( 1 ) 
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rvcm_Error rvcm_SetQueueListenerTasks ( 
rv_Session session, 
unsigned long listenerTasks ); 

Purpose 

Change the listener tasks parameter of a queue member session. 



Remarks 

10 

Task capacity is the maximum number of tasks that a listener can accept. When the 
number of accepted tasks reaches this maximum, the listener cannot accept additional 
tasks until it completes one or more of them. 



15 When the scheduler receives a task, it assigns the task to the listener (a queue 
member) with the greatest listener weight-unless the pending tasks assigned to that 
listener exceed its task capacity. When the preferred listener has too many tasks, the 
scheduler assigns the new inbound task to the listener with the next greatest listener 
weight. 

20 

Enabling a session as a queue member tacitly sets its listener tasks parameter to 
DEFAULTLISTENERTASKS (1). 

Programmers can tune task capacity based on two factors: 

25 

■ Multi-tasking program on multiprocessing hardware. 



On a multiprocessing computer, a multi-threaded program that devotes n 
threads and n processors to inbound tasks has task capacity n. 

Communication time lag. 



In most distributed queue applications, the communication time is < 
insignificant fraction of the task turnaround time. That is, the time required 
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assign "a task and signal its completion is very small compared to the time 
required to process the task itself. For example, when average task turnaround 
time is 2000 milliseconds, of which communication time contributes only 10 
milliseconds to the total, then task capacity is the same as the number of 
5 processors or threads. 

However, in some situations communication time can be significant--for 
example, when the queue members are distributed at distant sites connected by 
a Wide Area Network (WAN). When communication time is significant, the 

10 meaning of task capacity changes; instead of signifying the number of tasks 

that a listener can process concurrently, it signifies the number of tasks that 
can fill the listener's capacity despite the communication time lag. For 
example, when the average task turnaround time is 1500 milliseconds, of 
which the average task processing time contributes 1000 milliseconds to the 

15 total, then setting the task capacity to 3 minimizes the listener's idle time 

between tasks. 

When tuning task capacity to compensate for communication time lag, balance 
is critical. Underloading a listener (by setting its tasks capacity too low) can 
20 cause the listener to remain idle while it waits for the schedule to assign its 

next task. Conversely, overloading a listener (by setting its task capacity too 
high) can cause some assigned tasks to wait, while other listeners that might 
have accepted those tasks remain idle. 

25 Parameters 



Parameter 


Description 


session 


A session in a distributed queue. 


listenerTasks 


This value becomes the new listener ta 


sk capacity of 




the session. The value must be 1 or greater. I 
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Errors 



RVCMERR Code 


Indicates 


RVCM_OK 


No error. The call completed 
successfully. 


RVCM_ERR_INVALID_SESSION 


The function received a session 
argument that is not a valid 
rv Session (for example, NULL, or 
a session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an illegal 
argument. 


RVCM_ERR_SESSION_NOT_ENA 
BLED 


The function received a session that 
is not enabled for delivery tracking. 



5 See Also 

rvcm_QueueListenerTasks (), below. 

10 

rvcmQueueListenerTasksO 

Function 
IS Declaration 

#define DEFAULT_LISTENER_WEIGHT (1) 
rvcmErrpr rvcm_QueueListenerTasks ( 
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rv_Session session, 
unsigned long* listenerTasks ); 

Purpose 

5 

Extract the listener tasks parameter of a queue member session. 
Remarks 

10 Task capacity is the maximum number of tasks that a listener can accept. When the 
number of accepted tasks reaches this maximum, the listener cannot accept additional 
tasks until it completes one or more of them. 

When the scheduler receives a task, it assigns the task to the listener (a queue 
15 member) with the greatest listener weight-uniess the pending tasks assigned to that 
listener exceed its task capacity. When the preferred listener has too many tasks, the 
scheduler assigns the new inbound task to the listener with the next greatest listener 
weight. 

20 Enabling a session as a queue member tacitly sets its listener tasks parameter to 
DEFAULT JJSTENKRTASKS (1). 

Parameters 



Parameter 


Description 


session 


A session in a distributed queue. 


listenerTasks 


This location receives the current listener task capacity 
of the session. 



Errors 
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RVCMERR Code 


Indicates 


RVCM_OK 


No error. The call completed successfully. 



RVCM ERR Code 


Indicates 


RVCM_ERR_INVALID_SESSION 


The function received a 
session argument that is not 
a valid rvsession (for 
example, NULL, or a 
session that has already 
terminated). 


RVCM_ERR_BAD_ARG 


The function received an 
illegal argument. 


RVCM_ERR_SESSION_NOT_ENABLED 


The function received a 
session that is not enabled 
for delivery tracking. 



See Also 

rvcm_SetQueueListenerTasks(), above. 
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